이클립스 한글 깨짐 문제 해결 가이드

이클립스에서 개발하며 한글이 깨져 답답했던 경험, 많으실 겁니다. 특히 콘솔, 편집기, 심지어 애플리케이션 실행 결과에서까지 알 수 없는 글자들이 나타나면 작업 흐름이 끊기기 마련인데요. 이 글은 이클립스 한글 깨짐 문제의 근본 원인을 파악하고, 누구나 쉽게 따라 할 수 있는 단계별 해결책을 제시하여 쾌적한 개발 환경을 만드는 데 도움을 드릴 것입니다.

이클립스 한글 깨짐, 왜 발생할까요?

이클립스에서 한글이 깨지는 현상은 대부분 ‘문자 인코딩(Character Encoding)’ 불일치에서 비롯됩니다. 컴퓨터는 문자를 숫자로 변환하여 저장하고 표현하는데, 이 과정에서 어떤 규칙(인코딩 방식)을 따르는지에 따라 결과가 달라집니다. 주로 발생하는 문제는 다음과 같습니다.

운영체제 기본 인코딩(MS949/EUC-KR)과 이클립스/프로젝트 인코딩(UTF-8)의 충돌: 윈도우 운영체제의 기본 인코딩은 오랫동안 MS949(CP949) 또는 EUC-KR이었습니다. 반면, 현대적인 개발 환경에서는 전 세계 언어를 아우를 수 있는 UTF-8을 표준으로 사용합니다. 이 두 인코딩 방식이 혼재될 때 한글이 제대로 표현되지 못하고 깨지는 현상이 발생합니다.
각기 다른 설정 지점: 이클립스에는 워크스페이스, 프로젝트, 파일, 컴파일러, 실행 환경, 심지어 JVM(Java Virtual Machine) 인자 등 여러 설정 지점이 존재하며, 이 중 하나라도 다른 인코딩을 사용하면 문제가 발생합니다.
협업 환경의 중요성: 특히 팀 프로젝트나 오픈소스 프로젝트에서는 모든 개발자가 동일한 인코딩 설정을 유지하는 것이 중요합니다. 인코딩 문제가 발생하면 코드 가독성 저하를 넘어 컴파일 오류나 런타임 오류로까지 이어질 수 있습니다.

단계별 이클립스 한글 깨짐 해결 방법

이클립스에서 한글 깨짐 문제를 해결하기 위한 가장 중요한 원칙은 모든 설정 지점에서 ‘UTF-8’을 일관되게 적용하는 것입니다. 다음 단계를 차근차근 따라 해 보세요.

1. 워크스페이스 및 텍스트 파일 인코딩 설정

이클립스에서 생성되거나 열리는 모든 파일에 대한 기본 인코딩을 설정하는 가장 기본적인 단계입니다.

Eclipse 상단 메뉴: Window > Preferences를 클릭합니다. (macOS의 경우 Eclipse > Preferences)
환경설정 창: General > Workspace로 이동합니다.
Text file encoding: Default (MS949) 대신 Other를 선택하고 드롭다운 목록에서 UTF-8을 선택합니다.
New text file line delimiter: 운영체제 환경에 따라 Windows 또는 Unix를 선택할 수 있으며, 일반적으로 Windows를 사용합니다.
적용: Apply and Close를 클릭하여 설정을 저장합니다.

팁: 기존에 생성된 프로젝트나 파일의 인코딩은 이 설정으로 변경되지 않습니다. 기존 프로젝트의 경우, 프로젝트별로 인코딩을 재설정해야 합니다.

2. 프로젝트별 인코딩 설정 (필수)

워크스페이스 인코딩을 변경했더라도, 기존 프로젝트는 이전 설정을 유지할 수 있습니다. 각 프로젝트의 인코딩도 UTF-8로 변경해야 합니다.

Package Explorer: 인코딩을 변경할 프로젝트를 마우스 오른쪽 버튼으로 클릭합니다.
속성: Properties를 선택합니다.
리소스: Resource로 이동합니다.
Text file encoding: Inherited from container (UTF-8) 또는 Other를 선택하고 UTF-8을 지정합니다.
적용: Apply and Close를 클릭합니다.

참고: 여러 프로젝트를 동시에 변경해야 한다면, 모든 프로젝트를 선택하고 Properties를 열어 한 번에 변경할 수도 있습니다.

3. Java 컴파일러 인코딩 설정

Java 소스 코드를 컴파일할 때 사용되는 인코딩 방식을 지정합니다. 이 설정이 올바르지 않으면 컴파일 시 한글 주석이나 문자열 리터럴에서 오류가 발생할 수 있습니다.

Eclipse 상단 메뉴: Window > Preferences를 클릭합니다.
환경설정 창: Java > Compiler로 이동합니다.
Encoding: Use default encoding 체크박스를 해제하고, 드롭다운 목록에서 UTF-8을 선택합니다.
적용: Apply and Close를 클릭합니다.

팁: 최신 Eclipse 버전 및 JDK에서는 기본적으로 UTF-8을 권장하며, 특별한 경우가 아니라면 이 설정은 자동으로 적용되어 있을 가능성이 높습니다. 하지만 한글 깨짐 문제가 지속된다면 반드시 확인해야 할 부분입니다.

4. 실행 환경 (Run Configuration) 인코딩 설정

애플리케이션을 실행할 때 콘솔이나 로그 파일 등에 출력되는 한글이 깨지는 경우, 실행 환경의 인코딩을 확인해야 합니다.

Run 메뉴: Run > Run Configurations...를 클릭합니다.
실행 구성: 왼쪽 목록에서 실행 중인 애플리케이션 유형(e.g., Java Application, Maven Build)을 선택하고, 해당 실행 구성을 클릭합니다.
Common 탭: 오른쪽 설정 창에서 Common 탭을 클릭합니다.
Encoding: Other를 선택하고 UTF-8을 지정합니다.
적용: Apply를 클릭하고 Run 또는 Close를 클릭합니다.

팁: 기존 실행 구성뿐만 아니라 새로 생성되는 모든 실행 구성에 대해 이 설정을 적용하는 것이 좋습니다.

5. JVM (Java Virtual Machine) 인자 추가

이클립스 자체나 실행되는 애플리케이션의 JVM 레벨에서 인코딩을 강제로 UTF-8로 지정하는 방법입니다. 이는 매우 강력한 해결책 중 하나입니다.

5.1. Eclipse IDE 자체 JVM 인자 설정 (eclipse.ini)

이클립스 IDE가 시작될 때 사용되는 인코딩을 설정합니다. 이클립스 내부 UI나 콘솔 등에서 한글이 깨질 때 유용합니다.

eclipse.ini 파일 찾기: 이클립스가 설치된 폴더로 이동하여 eclipse.ini 파일을 찾습니다.
파일 편집: 텍스트 편집기(메모장, VS Code 등)로 eclipse.ini 파일을 엽니다.
인자 추가: -vmargs 라인 아래에 다음 두 줄을 추가합니다.
-Dfile.encoding=UTF-8 -Dconsole.encoding=UTF-8
예시:
-startup plugins/org.eclipse.equinox.launcher_1.6.900.v20240717-1941.jar --launcher.library plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.3.0.v20240717-1941 -vmargs -Dosgi.requiredJavaVersion=17 -Dfile.encoding=UTF-8 -Dconsole.encoding=UTF-8 -Xms256m -Xmx2048m
저장 및 재시작: 파일을 저장하고 이클립스를 완전히 종료한 후 다시 시작합니다.

5.2. 애플리케이션 실행 시 JVM 인자 추가 (Run Configurations)

실행되는 애플리케이션에 특정 JVM 인자를 전달하여 인코딩 문제를 해결합니다.

Run 메뉴: Run > Run Configurations...를 클릭합니다.
실행 구성: 실행 중인 애플리케이션 유형을 선택하고, 해당 실행 구성을 클릭합니다.
Arguments 탭: Arguments 탭을 클릭합니다.
VM arguments: 텍스트 상자에 다음 인자를 추가합니다.
-Dfile.encoding=UTF-8
적용: Apply를 클릭하고 Run 또는 Close를 클릭합니다.

6. 웹 서버 인코딩 설정 (웹 애플리케이션 개발 시)

Tomcat과 같은 웹 서버를 사용하는 웹 애플리케이션 개발 시에는 웹 서버 자체의 인코딩 설정도 중요합니다. 특히 URL 파라미터나 요청 본문에 한글이 포함될 때 문제가 자주 발생합니다.

6.1. Tomcat server.xml 설정

Server 탭: 이클립스 Servers 탭에서 해당 Tomcat 서버를 더블 클릭하여 설정 파일을 엽니다.
server.xml: Overview 화면에서 Open launch configuration 또는 server.xml 파일을 직접 엽니다.
Connector 태그 수정: <Connector> 태그 내에 URIEncoding="UTF-8" 속성을 추가합니다.
xml <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" URIEncoding="UTF-8" />
저장 및 재시작: 파일을 저장하고 Tomcat 서버를 재시작합니다.

6.2. Tomcat VM arguments 설정

Tomcat 서버를 이클립스 내에서 실행할 때 JVM 인자를 추가하여 인코딩을 설정할 수 있습니다.

Server 탭: Servers 탭에서 해당 Tomcat 서버를 마우스 오른쪽 버튼으로 클릭하고 Open을 선택합니다.
Launch Configuration: General Information 섹션에서 Open launch configuration 링크를 클릭합니다.
Arguments 탭: Arguments 탭으로 이동합니다.
VM arguments: VM arguments 섹션에 다음을 추가합니다.
-Dfile.encoding=UTF-8
적용 및 재시작: Apply를 클릭하고 Tomcat 서버를 재시작합니다.

7. 폰트 문제 확인

매우 드물지만, 이클립스에서 사용되는 폰트가 한글을 지원하지 않거나 손상되었을 경우에도 한글이 깨져 보일 수 있습니다.

Eclipse 상단 메뉴: Window > Preferences를 클릭합니다.
환경설정 창: General > Appearance > Colors and Fonts로 이동합니다.
폰트 확인: Basic > Text Font 및 Java > Java Editor Text Font 등 주로 사용하는 폰트를 확인합니다.
한글 지원 폰트 선택: Edit 버튼을 클릭하여 D2Coding, 나눔고딕코딩, Malgun Gothic(맑은 고딕) 등 한글을 잘 지원하는 폰트로 변경합니다.
적용: Apply and Close를 클릭합니다.

최종 점검 및 유의사항

일관성 유지: 위에서 제시된 모든 인코딩 설정을 UTF-8로 일관되게 적용하는 것이 핵심입니다. 한 군데라도 빠뜨리면 문제가 재발할 수 있습니다.
새 프로젝트 시작: 가능하다면, 새로운 프로젝트를 시작할 때부터 모든 인코딩 설정을 UTF-8로 맞춰두는 것이 가장 좋습니다.
소스 코드 재저장: 인코딩 설정을 변경한 후에도 기존에 깨져 보이던 한글이 포함된 소스 코드는 다시 한글로 수정하고 저장해야 정상적으로 표시될 수 있습니다.
버전 관리 시스템(VCS): Git과 같은 VCS를 사용할 때는 .gitattributes 파일에 *.java text eol=lf encoding=UTF-8와 같이 파일별 인코딩 설정을 명시하여 협업 환경에서 일관성을 유지하는 것이 중요합니다.
외부 도구와의 연동: 이클립스 외에 빌드 도구(Maven, Gradle), 터미널 프로그램 등을 함께 사용할 경우, 해당 도구들의 인코딩 설정도 함께 확인해야 합니다.
운영체제 언어 설정: 드물지만, 윈도우 운영체제의 ‘국가 또는 지역 > 관리자 옵션 > 시스템 로캘 변경’ 설정이 베타: 세계 언어 지원을 위해 Unicode UTF-8 사용으로 되어 있는지 확인하는 것도 도움이 될 수 있습니다. (2025년 기준, 윈도우 10/11에서는 이 옵션을 켜는 것이 권장됩니다.)

이클립스 한글 깨짐 문제는 개발 초보자부터 숙련된 개발자까지 누구나 겪을 수 있는 흔한 문제입니다. 이 가이드의 해결책들을 통해 더 이상 인코딩 문제로 작업 흐름이 방해받지 않고, 효율적인 개발을 이어나갈 수 있기를 바랍니다.

자료 종류	설명	링크
Eclipse 공식 문서	이클립스 환경설정에 대한 일반적인 가이드	Eclipse 도움말 시스템
Java 공식 문서	Java 문자 인코딩 및 JVM 인자 관련 상세 정보	Oracle Java Documentation
Tomcat 공식 문서	Tomcat 서버 인코딩 설정 관련 상세 정보	Apache Tomcat Documentation
개발자 커뮤니티	다양한 개발자들이 질문하고 답변하는 포럼	Stack Overflow (Eclipse)
운영체제 도움말	윈도우 등 OS 인코딩 및 로캘 설정 관련	Microsoft 지원