"코드는 맞는데 왜 안 돌아가지?"당신을 밤새우게 만든 UTF-8 BOM 에러완벽 해결 가이드

 

 

로직도 완벽하고 문법도 이상 없는데 계속 에러가 난다면, 범인은 눈에 보이지 않는 곳에 숨어 있을 수 있습니다. 오늘은 초보자부터 현직 개발자까지 당황하게 만드는 BOM 문제의 정체와 10초 해결법을 파헤칩니다.

​

범인은 눈에 보이지 않는 곳에 있다

열심히 코딩을 마쳤습니다. 로직도 완벽하고, 문법 오류도 없습니다. 그런데 실행하면 알 수 없는 Syntax Error나 깨진 문자가 출력됩니다. 코드를 처음부터 다시 읽어봐도 이상한 곳이 없습니다. 도대체 뭐가 문제일까요?

범인은 파일 맨 앞에 조용히 숨어 있는 3바이트짜리 유령, BOM(Byte Order Mark)입니다.

​

BOM이란 무엇인가?

BOM은 파일 맨 앞에 자동으로 삽입되는 0xEF, 0xBB, 0xBF라는 3바이트 데이터입니다. 원래는 "이 파일은 UTF-8로 작성됐다"는 힌트를 주기 위해 마이크로소프트 윈도우 환경에서 도입됐습니다. 문제는, 텍스트 에디터에서는 보이지 않지만 Python, PHP, Node.js 같은 인터프리터는 이걸 코드로 오인해 에러를 터뜨린다는 점입니다.

증상은 보통 이렇게 나타납니다.

​

증상 1

SyntaxError: invalid character

​

증상 2

파일 첫 줄에  출력

​

증상 3

JSON.parse() 파싱 실패

​

세 증상 모두 공통점이 있습니다. 코드 자체는 문제가 없고, 파일의 맨 첫 번째 바이트에서 에러가 발생한다는 것입니다.

​

툴별 10초 해결 매뉴얼

1. VS Code

우측 하단의 UTF-8 with BOM 클릭 → Reopen with Encoding 또는 Save with Encoding 선택 → UTF-8을 고르면 끝납니다.

​

2. 메모장 (Windows)

'다른 이름으로 저장' 클릭 → 하단 인코딩 드롭다운에서 UTF-8 선택. "UTF-8 (BOM 포함)"이 아닌 일반 UTF-8을 선택해야 합니다. BOM이 없는 것이 현대 웹 표준입니다.

​

3. Python 스크립트로 일괄 제거

수십, 수백 개의 파일이 문제라면 아래 스크립트를 활용하세요. utf-8-sig 인코딩으로 읽으면 BOM이 자동으로 제거됩니다.

# BOM 제거 스크립트 — utf-8-sig로 읽고 utf-8로 다시 저장

with open('file.txt', 'r', encoding='utf-8-sig') as f:

content = f.read()

​

with open('file.txt', 'w', encoding='utf-8') as f:

f.write(content)

​

왜 'utf-8-sig'가 아닌 'utf-8'인가?

결론부터 말하면, 현대 개발 환경에서 BOM은 필요 없습니다. BOM은 원래 UTF-16처럼 바이트 순서가 중요한 인코딩에서 "어느 방향으로 읽어야 하는지" 알려주기 위해 탄생했습니다. UTF-8은 바이트 순서가 고정돼 있어 BOM이 원래부터 불필요합니다.

​

BOM 있음 (utf-8-sig)

Windows 메모장 기본값

Linux/Unix에서 에러 유발

JSON 파싱 실패 원인

​

BOM 없음 (utf-8)

웹 표준 · RFC 3629

Linux/Unix/Mac 기본값

Python · Node.js 권장 설정

​

윈도우와 호환성을 위해 도입된 BOM이, 오히려 현대의 크로스 플랫폼 개발 환경에서 독이 되는 이유가 여기 있습니다. 팀 프로젝트라면 에디터 설정을 UTF-8 (no BOM)으로 통일하는 것이 가장 확실한 예방책입니다.

​

기술적 디테일이 전체 시스템을 결정합니다

"눈에 보이지 않는 3바이트가 전체 파이프라인을 멈춥니다. 작은 설정 하나가 얼마나 큰 영향을 미치는지, 오늘 이 에러가 잘 보여줍니다."

​

오늘 배운 인코딩 지식은 단순히 에러 하나를 해결하는 데서 끝나지 않습니다. 파일 인코딩을 의식하는 습관은 API 연동, 데이터 파이프라인, 다국어 서비스 개발 등 모든 영역에서 버그를 미연에 방지하는 기반이 됩니다. 견고한 시스템은 이런 작은 디테일의 합계입니다.