인코딩 자동화 스크립트, 배치파일과 PowerShell 및 Python으로 폴더 일괄 유니코드 변환

이 글은 인코딩 자동화와 관련된 실무 가이드를 제공하는 기술 블로그 게시물입니다. 콘텐츠는 Windows 환경에서 배치파일/PowerShell로 폴더 전체를 일괄 변환하는 방법, Python·WSL(iconv) 기반 스크립트, VS Code 및 GUI 도구 활용법, GitHub Actions를 통한 CI 자동화까지 실무에서 바로 적용 가능한 예제와 트러블슈팅 팁을 포함합니다. 본문에서는 ANSI→UTF‑8 변환(특히 BOM 유무 선택), 대규모 폴더 처리, 로그 기록, Windows 10/11/12 및 PowerShell 7+ 호환성 등 검색 트래픽을 고려한 키워드(인코딩 스크립트 자동화, 배치파일 인코딩, PowerShell UTF-8 변환 등)를 자연스럽게 반영해 설명합니다.

왜 인코딩 자동화가 필요한가? (서론 + 문제제기)

웹 문서, 블로그 글, CSV/데이터 파일 등에서 인코딩 불일치로 인한 '문자 깨짐'은 매우 흔한 문제입니다. 특히 로컬에서 작성한 문서를 여러 사람과 공유하거나 공개 저장소에 푸시할 때, 파일 인코딩이 ANSI(CP949) 등으로 남아 있으면 브라우저나 에디터에서 한글이 깨질 수 있습니다. 반복적으로 여러 폴더와 파일을 일일이 열어 변환하는 수작업은 시간 낭비이며 휴먼 에러를 유발합니다.

• 자동화 필요성: 폴더/하위폴더를 한 번에 처리해 반복작업을 최소화
• 목표: ANSI → UTF‑8 (BOM 유무 선택), 파일 유형 필터링(.txt, .md, .html, .csv 등)
• 적용 범위: 로컬 개발환경, 블로그 콘텐츠, Git 레포지토리 커밋 전 처리

방법1: PowerShell 배치파일 (초보자 추천)

PowerShell은 Windows 환경에서 가장 손쉽게 인코딩을 일괄 변환할 수 있는 도구입니다. 아래 스크립트는 지정 폴더의 하위 폴더까지 재귀적으로 탐색해 텍스트 파일을 감지하고, 원본 인코딩(기본값: 시스템 로컬 인코딩)으로 읽어 UTF‑8(=BOM 없음)으로 덮어씁니다. 변환 로그를 남기므로 실패 파일을 추적하기 쉽습니다.

# Save as Convert-Encoding.ps1
param(
    [string]$Path = ".",
    [string[]]$IncludeExtensions = @("*.txt","*.md","*.html","*.csv"),
    [string]$Log = "encoding_log.txt",
    [switch]$UseBOM
)

$logPath = Join-Path $Path $Log
"인코딩 변환 시작: $(Get-Date -Format u)" | Out-File $logPath -Encoding UTF8

Get-ChildItem -Path $Path -Recurse -File -Include $IncludeExtensions | ForEach-Object {
    try {
        $full = $_.FullName
        $raw = Get-Content -LiteralPath $full -Encoding Default -Raw
        $utf8Enc = if ($UseBOM) { [System.Text.UTF8Encoding]::new($true) } else { [System.Text.UTF8Encoding]::new($false) }
        [System.IO.File]::WriteAllText($full, $raw, $utf8Enc)
        "$(Get-Date -Format u) ✓ $full" | Add-Content -Path $logPath -Encoding UTF8
    } catch {
        "$(Get-Date -Format u) ✗ $full - $_" | Add-Content -Path $logPath -Encoding UTF8
    }
}

사용 팁:

• PowerShell 7 이상을 권장합니다(크로스 플랫폼 호환성 향상).
• 관리자 권한이 필요한 경로가 있으면 관리자 권한으로 실행하세요.
• 변환 전 백업을 권장합니다. 테스트용 파일로 먼저 점검하세요.

방법2: Python 스크립트 (가장 강력)

Python은 인코딩 자동 감지 라이브러리(chardet 또는 charset-normalizer)를 활용해 다양한 인코딩을 정확히 판별하고 변환하는 데 유용합니다. 아래 예시는 chardet을 사용한 실전 스크립트입니다. 대용량 파일 처리 시에는 스트리밍 또는 멀티프로세싱을 고려하세요.

# encoding_auto.py
import sys
from pathlib import Path
import chardet
from datetime import datetime

EXTS = {'.txt', '.md', '.html', '.csv'}

def detect_encoding(data: bytes):
    result = chardet.detect(data)
    return result.get('encoding')

def convert_file(path: Path, use_bom: bool = False):
    raw = path.read_bytes()
    enc = detect_encoding(raw) or 'utf-8'
    enc_lower = enc.lower()
    if enc_lower in ('utf-8', 'utf_8'):
        return f"skipped: {path.name} already UTF-8"
    try:
        text = raw.decode(enc, errors='replace')
        encoding = 'utf-8-sig' if use_bom else 'utf-8'
        path.write_text(text, encoding=encoding)
        return f"converted: {path.name} ({enc} → UTF-8)"
    except Exception as e:
        return f"error: {path.name} - {e}"

def auto_encode_folder(folder: str, use_bom: bool = False):
    p = Path(folder)
    log_path = p / "encoding_log.txt"
    with log_path.open('a', encoding='utf-8') as log:
        log.write(f"변환 시작: {datetime.utcnow().isoformat()}Z\n")
        for f in p.rglob('*'):
            if f.is_file() and f.suffix.lower() in EXTS:
                result = convert_file(f, use_bom)
                log.write(result + "\n")
                print(result)

if __name__ == "__main__":
    target = sys.argv[1] if len(sys.argv) > 1 else "."
    auto_encode_folder(target)

설치:

• pip install chardet

주의사항:

• chardet은 통계 기반 탐지이므로 100% 정확하지 않습니다. 중요한 파일은 변환 후 샘플 확인 필요.
• Git 저장소에서는 커밋 전에 변환 스크립트를 실행하도록 pre-commit 훅을 설정하면 안전합니다.

방법3: Git Bash / WSL (개발자 추천)

리눅스 환경의 iconv를 활용하면 빠르게 인코딩을 변환할 수 있습니다. WSL이나 Git Bash에서 사용 가능한 간단한 스크립트 예시는 다음과 같습니다.

#!/bin/bash
# encode-all.sh
# Usage: ./encode-all.sh [dir]
DIR=${1:-.}
find "$DIR" -type f \( -name "*.txt" -o -name "*.md" -o -name "*.html" -o -name "*.csv" \) -print0 | while IFS= read -r -d '' file; do
    # 감지 불가 시 기본 인코딩을 CP949로 가정 (한국어 Windows)
    iconv -f CP949 -t UTF-8 "$file" -o "$file.tmp" && mv "$file.tmp" "$file" && echo "✓ $file"
done > encoding_log.txt

팁:

• iconv 실패 시 원본을 보존하도록 임시 파일 및 백업 전략을 사용하세요.
• 파일 인코딩이 다양하다면 먼저 hexdump 또는 file 명령으로 검토합니다.

방법4: VS Code + 확장프로그램 (가장 편함)

VS Code는 파일 인코딩 변경을 GUI로 쉽게 지원합니다. 확장 프로그램을 추가하면 여러 파일을 일괄로 처리하거나, 열 때 자동으로 인코딩을 감지해 변경할 수 있습니다.

• Change File Encoding (by jinkai) — 개별 파일 인코딩 변경을 쉽게 수행
• Settings → Files: Encoding으로 기본 에디터 인코딩을 UTF-8로 고정

공식 확장 링크(참고): VS Code 확장: Change File Encoding

방법5: GitHub Actions 자동화 (최신 트렌드)

레포지토리에 푸시될 때마다 자동으로 인코딩을 정리하도록 GitHub Actions 워크플로를 구성하면 협업 시 인코딩 문제를 사전 차단할 수 있습니다.

# .github/workflows/encode.yml
name: Auto Encode
on:
  push:
    branches: [ main ]
jobs:
  encode:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Convert text files to UTF-8
        run: |
          find . -type f \( -name "*.txt" -o -name "*.md" -o -name "*.html" -o -name "*.csv" \) -print0 | \
          xargs -0 -n1 -P4 -I{} sh -c 'file="{}"; iconv -f CP949 -t UTF-8 "$file" -o "$file.tmp" && mv "$file.tmp" "$file" || echo "skip: $file"'

주의:

• CI에서 자동 변환 시 의도치 않은 변경이 커밋될 수 있으므로 PR 과정에서 검토를 권장합니다.
• 여러 인코딩이 섞여 있는 레포지토리는 사전 테스트가 필수입니다.

방법6: GUI 툴 추천 (명령줄 싫은 사람)

명령줄이 익숙하지 않다면 다음 GUI 툴을 사용해 대량 파일의 인코딩을 변경할 수 있습니다. 아래는 공식 사이트 또는 배포 페이지로 연결되는 링크입니다.

• BulkFileChanger (NirSoft) — 파일 메타데이터 및 인코딩 일괄 변경
• PowerToys (Microsoft) — 유틸리티 모음, 텍스트 추출 등 보조 기능
• Notepad++ — 인코딩 변경 기능과 플러그인 지원

트러블슈팅 및 성능 최적화

• 여전히 깨짐: 특정 파일은 원본 인코딩을 정확히 추정할 수 없으므로 수동으로 인코딩을 지정해 변환하세요. PowerShell에서는 [System.Text.UTF8Encoding]::new($true)로 BOM 추가가 가능합니다.
• 대용량 폴더 처리 느림: Python의 multiprocessing, GNU parallel 또는 find|xargs -P 를 이용해 병렬 처리하세요.
• Git 충돌 방지: 변환 전후 파일 변경사항을 검토한 뒤 커밋하세요. 자동 변환은 PR 단계에서 수행하는 것이 안전합니다.
• Windows 12 및 최신 환경: PowerShell 7.3+ 및 최신 iconv, Python 3.10+ 환경에서 테스트 권장.

PowerShell 공식 문서 바로가기 >

마무리 및 권장 설정

실무에서는 다음 권장 설정을 우선 적용하면 인코딩 관련 문제를 크게 줄일 수 있습니다.

• 에디터 기본 인코딩을 UTF‑8로 고정(예: VS Code settings)
• 새 파일 생성 시 BOM 사용 여부 정책 결정(팀 표준화)
• 커밋 전 자동 검사/변환(pre-commit 또는 CI) 도입
• 중요한 파일은 변환 전 백업 유지

위 가이드는 배치파일·PowerShell·Python·WSL(iconv)·GitHub Actions·VS Code·GUI 도구를 아우르는 통합 솔루션입니다. 환경에 맞는 방법을 선택해 자동화 파이프라인을 구축하면 반복작업을 크게 줄이고 인코딩 문제로 인한 콘텐츠 깨짐을 예방할 수 있습니다.