VSCode Spring Boot 한글 깨짐 해결: UTF-8 인코딩 설정 완벽 정리

열심히 만든 API에서 한글이 '???'나 알 수 없는 외계어로 나올 때, 사실 이 부분이 가장 번거로우시죠? 분명히 코드는 잘 짰는데 화면이나 로그에서 한글만 뭉개지면 의욕이 꺾이기 마련입니다. 막상 찾아보면 IDE 설정부터 서버 옵션까지 용어가 너무 어려운데요, 인코딩 문제는 마치 '서로 다른 언어를 쓰는 사람들이 통역사 없이 대화하는 것'과 같습니다. 오늘은 2026년 표준 환경에서 한글 깨짐을 뿌리 뽑는 확실한 해결책을 정리해 드릴게요.

한글 깨짐 현상이 발생하는 3대 포인트

한글이 깨지는 이유는 다양하지만, 크게 세 가지 지점에서 통역(인코딩) 오류가 발생합니다. 내가 겪고 있는 문제가 어디에 해당하시나요? 개인적으로 이 지점을 정확히 파악하는 것이 삽질을 줄이는 가장 핵심적인 지점이라고 생각합니다.

발생 위치	현상	체크 리스트
편집기 (IDE)	VSCode 코드 내 한글 주석이나 문자열이 깨짐	파일 인코딩 설정 (UTF-8)
서버 응답 (HTTP)	브라우저나 Postman 결과창에 '???' 출력	Spring Boot Encoding Filter
콘솔 로그 (Console)	터미널(Terminal) 창의 로그만 깨져서 보임	JVM 실행 인자 (-Dfile.encoding)

단계별 한글 인코딩 설정 및 해결 방법

가장 확실한 방법은 모든 환경을 UTF-8로 통일하는 것입니다. VSCode 환경에서 하나씩 따라 해보세요. 저도 처음엔 헷갈렸던 부분인데, 설정 파일 한 줄만 추가해도 해결될 일을 엉뚱한 곳에서 헤매는 경우가 많더라고요.

1. application.properties 설정: 스프링 부트 서버가 나가는 데이터에 강제로 UTF-8을 입히도록 명령합니다.
   • server.servlet.encoding.charset=UTF-8
   • server.servlet.encoding.force=true
   • server.servlet.encoding.enabled=true
2. VSCode 파일 인코딩 확인: 하단 상태 표시줄에 'UTF-8'이라고 적혀 있는지 확인하세요. 만약 'EUC-KR'로 되어 있다면 클릭해서 'Save with Encoding' -> 'UTF-8'로 변경해야 합니다.
3. JVM 실행 옵션 추가: 프로젝트 실행 시 한글을 인식하도록 인자를 넣어줍니다. 이건 저만 아는 건데, .vscode/launch.json 파일의 vmArgs 항목에 -Dfile.encoding=UTF-8을 추가하면 콘솔 깨짐까지 깔끔하게 잡힙니다.

이건 모르면 손해 보는 꿀팁인데, 만약 DB에서 가져온 데이터만 깨진다면 application.properties의 JDBC URL 뒤에 ?characterEncoding=UTF-8 옵션이 빠져있는지 꼭 확인해 보세요.

설정이 꼬이면 오히려 독이 됩니다

무조건 모든 곳에 '강제 설정(force)'을 거는 게 항상 정답은 아닙니다. 솔직히 말씀드리면, 이미 시스템 전체가 EUC-KR로 굳어진 오래된 외부 API와 통신할 때는 이 설정이 오히려 통신 오류를 일으키는 부작용을 낳을 수 있습니다.
 
또한, 윈도우(Windows) 운영체제 자체의 기본 인코딩(MS949)과 부딪히는 경우도 종종 발생합니다. 이 단계에서 흔히 하는 실수는 소스 코드는 UTF-8인데 실행 환경만 윈도우 기본값으로 두는 것이죠. 2026년 최신 윈도우 11 환경에서는 '시스템 로캘 설정'에서 'Beta: 세계 언어 지원을 위해 유니코드 UTF-8 사용' 옵션을 체크하는 것만으로도 많은 문제가 해결되기도 합니다. 이 부분은 환경마다 차이가 크니 반드시 자신의 OS 설정도 함께 살펴보셔야 해요.

한글 깨짐 없는 쾌적한 개발 환경을 위하여

결국 인코딩 문제는 '약속'의 문제입니다. 내가 UTF-8로 보낼 테니, 너도 UTF-8로 받아달라고 명확히 선언하는 과정이죠. 제 생각에는 처음 프로젝트를 생성할 때 application.properties에 인코딩 설정을 미리 넣어두는 습관을 들이는 게 가장 유리해 보여요. 나중에 데이터가 쌓인 뒤에 인코딩을 바꾸려면 DB 데이터까지 변환해야 하는 대공사가 될 수 있거든요.

 
결국 핵심은 '일관성'입니다. 편집기, 서버, DB, 그리고 브라우저까지 이어지는 파이프라인 전체를 하나의 언어로 통일해 보세요. 이제 더 이상 '???' 때문에 스트레스받지 않고 오직 로직 구현에만 집중할 수 있을 겁니다. 여러분은 인코딩 문제로 몇 시간 동안 고생해 본 경험이 있으신가요? 혹은 저만 알고 있는 또 다른 한글 해결 비법이 있다면 무엇인가요?

VSCode Spring Boot Swagger 적용: 협업을 위한 API 문서화 자동화 가이드