React 한글 깨짐 해결: Visual Studio 2022에서 UTF-8로 저장하기

REACT · VISUAL STUDIO 2022 · UTF-8

React 화면의 한글 깨짐,
파일 인코딩부터 확인하세요

React 실행 후 한글이 이상한 문자로 표시된다면 소스 파일의 저장 인코딩을 먼저 확인해 보세요. 이 글은 기존 Visual Studio 2022 화면 예시를 바탕으로, 한글이 정상적으로 보이는 파일을 UTF-8로 저장하는 절차를 정리한 안내입니다.

핵심 순서

한글이 깨지는 위치 확인 → 원본 문자가 정상인지 확인 → UTF-8로 저장 → 다시 실행 → 브라우저 표시 확인

1. 한글이 깨지는 위치부터 구분하기

소스 파일, 브라우저 화면, API 응답 중 어디에서 한글이 깨지는지에 따라 확인할 곳이 달라집니다. 파일을 UTF-8로 저장하는 방법이 모든 한글 깨짐을 해결하는 것은 아닙니다.

깨진 문자를 그대로 다시 저장하지 마세요.

편집기에서 이미 한글이 잘못 보이면 원래 인코딩으로 다시 열어 정상 표시되는지 먼저 확인합니다. 이미 물음표나 대체 문자로 저장되어 원문이 손실된 경우에는 UTF-8로 바꾸기만 해서는 복구되지 않으며, Git 이력이나 백업에서 원본을 찾아야 합니다.

한글 문자열이 들어 있는 .js, .jsx, .ts, .tsx 등의 파일을 엽니다. 편집기에서 문장이 정상적으로 보이는지 확인한 뒤 진행합니다.

상단 파일(File) 메뉴에서 현재 파일의 다른 이름으로 저장(Save As) 항목을 선택합니다.

저장 대화상자의 저장 버튼 옆 화살표를 누르고 인코딩하여 저장(Save with Encoding)을 선택합니다.

고급 저장 옵션의 인코딩 목록에서 UTF-8 / 코드 페이지 65001 항목을 선택하고 확인합니다. 기존 글에서는 유니코드(서명 있는 UTF-8) — 코드 페이지 65001을 선택한 방법을 안내했습니다.

저장할 경로와 파일명이 기존 파일과 일치하는지 확인하세요. 별도 파일로 저장했다면 실제 프로젝트가 사용하는 파일에도 변경이 반영되어야 합니다.

변경 내용을 저장한 뒤 기존 프로젝트의 실행 방식으로 다시 확인합니다. 화면에 반영되지 않을 때에는 개발 서버를 재시작하고 브라우저를 새로고침합니다.

BOM은 파일 앞부분에 들어갈 수 있는 인코딩 식별 표시입니다. Visual Studio에서 말하는 “서명 있는 UTF-8”은 BOM이 포함된 UTF-8을 뜻합니다.

React에서 한글을 쓰기 위해 BOM이 반드시 필요한 것은 아닙니다.

핵심은 원본 문자가 정상인 상태에서 파일을 UTF-8로 저장하고, 읽는 쪽에서도 일치하는 인코딩으로 해석하는 것입니다. BOM 유무는 프로젝트와 사용 도구의 규칙에 맞추세요.

Visual Studio 2022와 Visual Studio Code는 서로 다른 편집기입니다. VS Code에서는 오른쪽 아래 상태 표시줄의 인코딩 항목을 클릭합니다.

메뉴	사용할 상황
Reopen with Encoding 인코딩하여 다시 열기	현재 파일의 바이트를 다른 인코딩으로 읽어 정상 문자인지 확인할 때
Save with Encoding 인코딩하여 저장	정상적으로 표시되는 문자를 UTF-8 등으로 변환해 저장할 때

프로젝트의 VS Code 기본 인코딩을 지정하려면 .vscode/settings.json의 기존 설정에 다음 항목을 병합할 수 있습니다.

{
  "files.encoding": "utf8"
}

이 설정만으로 기존 파일 전체가 자동 변환되지는 않습니다. 문제가 있는 파일은 개별적으로 확인해야 합니다.

컴포넌트에 아래처럼 고정 문구를 잠시 표시해 보세요.

export default function EncodingCheck() {
  return <p>한글 표시 확인: 안녕하세요.</p>;
}

고정 문구는 정상인데 서버에서 받은 값만 깨진다면, 브라우저 개발자 도구의 Network → 해당 API → Response에서 응답을 확인합니다. API 응답부터 깨져 있으면 소스 파일보다 서버의 문자 처리와 DB 원본 값을 먼저 확인합니다.

프로젝트가 직접 관리하는 HTML 진입 파일이 있다면 head 안의 문자셋 선언도 확인합니다.

<meta charset="UTF-8" />

이 선언은 HTML의 문자셋을 알려 주는 역할을 하며, 이미 손상된 JavaScript 문자열이나 API 데이터를 복구하지는 않습니다. HTML 파일 위치는 프로젝트 구성에 따라 다릅니다.

완료 체크