Korean IME Fix for VSCode
macOS VSCode에서 한글 입력 시 자모 분리 문제를 완전히 해결하는 확장 프로그램
![한글 입력 문제 해결]
🚨 문제 상황
macOS의 VSCode에서 한글을 입력할 때 다음과 같은 문제가 발생합니다:
입력하고 싶은 내용
한글
실제 VSCode에 표시되는 내용
하ㄴ글
한ㅡㄹ
자모가 분리되어 표시되는 심각한 문제 입니다.
✅ 해결 효과
Before (문제 상황)
입력: "한글테스트"
결과: "하ㄴ글테ㅅ트" ❌
After (확장 프로그램 설치 후)
입력: "한글테스트"
결과: "한글테스트" ✅
📦 설치 방법
방법 1: 직접 설치 (권장)
확장 프로그램 파일 다운로드
# 릴리즈 페이지에서 .vsix 파일 다운로드
curl -L -O https://github.com/jongsik-code/korean-ime-fix-pjs/releases/latest/download/korean-ime-fix-pjs-0.9.0.vsix
VSCode에 설치
code --install-extension korean-ime-fix-pjs-0.9.0.vsix
VSCode 재시작
# macOS에서 VSCode 완전 종료
pkill -f "Visual Studio Code"
# VSCode 재시작
code
방법 2: VSCode 마켓플레이스
- VSCode 열기
- 확장 프로그램 패널 열기 (
Cmd + Shift + X
)
- "Korean IME Fix" 검색
- "설치" 클릭
- VSCode 재시작
🎯 사용 방법
자동 활성화
- 확장 프로그램 설치 후 자동으로 활성화됩니다
- 별도 설정 없이 즉시 한글 입력이 개선됩니다
수동 제어
Command Palette (Cmd + Shift + P
)에서 다음 명령어 사용:
명령어 |
기능 |
Korean IME Fix: 한글 IME 수정 활성화 |
확장 기능 활성화 |
Korean IME Fix: 한글 IME 수정 비활성화 |
확장 기능 비활성화 |
Korean IME Fix: 상태 확인 |
현재 활성화 상태 확인 |
⚙️ 설정 옵션
설정 파일에서 직접 수정
설정 파일 열기: Cmd + Shift + P
→ Preferences: Open Settings (JSON)
{
"korean-ime-fix.enabled": true,
"korean-ime-fix.debugMode": false
}
설정 항목 설명
설정 |
기본값 |
설명 |
korean-ime-fix.enabled |
true |
확장 프로그램 활성화/비활성화 |
korean-ime-fix.debugMode |
false |
디버그 모드 (개발자용 로그 출력) |
UI에서 설정 변경
- 설정 열기:
Cmd + ,
- 검색: "Korean IME Fix"
- 원하는 옵션 체크/해제
📋 명령어 사용법
1. 확장 기능 활성화
Cmd + Shift + P → Korean IME Fix: 한글 IME 수정 활성화
결과: ✅ 한글 IME 수정이 활성화되었습니다.
2. 확장 기능 비활성화
Cmd + Shift + P → Korean IME Fix: 한글 IME 수정 비활성화
결과: ❌ 한글 IME 수정이 비활성화되었습니다.
3. 상태 확인
Cmd + Shift + P → Korean IME Fix: 상태 확인
결과: Korean IME Fix 상태: 활성화됨 ✅
🧪 정상 작동 테스트
테스트 방법
- 새 파일 생성:
Cmd + N
- 한글 입력 테스트:
안녕하세요
한글 입력이 정상적으로 됩니다
자모 분리 문제가 해결되었습니다
- 결과 확인: 자모가 분리되지 않고 완성된 글자로 표시
문제 지속 시 체크리스트
- [ ] VSCode 완전 재시작 했는가?
- [ ] 확장 프로그램이 활성화되어 있는가?
- [ ] macOS 키보드 설정이 "한국어 - 2-Set Korean"인가?
- [ ] VSCode 버전이 1.100.0 이상인가?
🔧 문제 해결
Q: 여전히 자모가 분리됩니다
A: 다음 단계를 순서대로 실행하세요:
VSCode 완전 재시작
pkill -f "Visual Studio Code"
code
확장 상태 확인
Cmd + Shift + P → Korean IME Fix: 상태 확인
수동으로 다시 활성화
Cmd + Shift + P → Korean IME Fix: 한글 IME 수정 활성화
Q: 확장 프로그램을 찾을 수 없습니다
A: 설치 상태 확인:
- 확장 프로그램 패널 열기:
Cmd + Shift + X
- "Korean IME Fix" 검색
- 설치되어 있는지 확인
- 비활성화되어 있다면 "활성화" 클릭
Q: 다른 에디터에서는 정상인데 VSCode에서만 문제입니다
A: 이는 VSCode의 Monaco Editor와 macOS IME 간의 호환성 문제입니다. 이 확장 프로그램이 정확히 그 문제를 해결합니다.
Q: 자동완성이 작동하지 않습니다
A: 한글 입력 최적화를 위해 일부 자동완성 기능이 조정되었습니다. 필요시 수동으로 설정을 변경할 수 있습니다:
{
"editor.quickSuggestions": {
"other": true,
"comments": true,
"strings": true
}
}
🔬 기술적 원리
문제의 원인
- VSCode의 Monaco Editor와 macOS의 IME(입력기) 간의 호환성 문제입니다.
- 에디터가 한글 조합 중 발생하는
composition
이벤트를 올바르게 처리하지 못해, 완성된 글자가 아닌 자모 단위로 분리되어 입력되는 현상이 발생합니다.
해결 방법
이 확장 프로그램은 VSCode의 핵심 설정을 최적화하여 이 문제를 근본적으로 해결합니다.
editor.accessibilitySupport: 'on'
설정 강제 적용
- 이 설정은 VSCode 에디터가 스크린 리더와 같은 보조 기술을 지원하도록 내부 동작을 변경합니다.
- 이 과정에서 IME 이벤트 처리 방식 또한 변경되어, 한글 조합이 정상적으로 이루어지도록 만듭니다. 이것이 문제 해결의 가장 핵심적인 원리입니다.
자동완성 기능 최적화
- 한글을 입력하는 도중, VSCode의 자동완성 및 코드 제안 기능이 나타나면서 조합 상태를 방해하는 경우가 많습니다.
- 이 확장 프로그램은
quickSuggestions
, suggestOnTriggerCharacters
등 관련 기능들을 비활성화하여, 오직 한글 입력에만 집중할 수 있는 환경을 제공합니다.
유니코드 하이라이트 조정
ㅎ
ㅏ
ㄴ
과 같은 한글 자모가 입력될 때, VSCode가 이를 비정상적인 문자로 간주하여 노란색으로 강조 표시하는 것을 방지합니다.
🖥 지원 환경
운영체제
- ✅ macOS 12.0 이상 (Monterey, Ventura, Sonoma, Sequoia)
- ❌ Windows (해당 문제 없음)
- ❌ Linux (해당 문제 없음)
VSCode 버전
- ✅ VSCode 1.100.0 이상
- ✅ VSCode Insiders
- ✅ Cursor (VSCode 기반 에디터)
한글 입력기
- ✅ macOS 기본 한글 입력기
- ✅ 구름 입력기
- ✅ 세벌식 입력기
📊 성능 영향
리소스 사용량
- 메모리: +2~3MB (미미한 증가)
- CPU: 0% (백그라운드 동작)
- 배터리: 영향 없음
다른 기능에 미치는 영향
- 자동완성: 일부 조정됨 (필요시 수동 설정 가능)
- 파일 편집: 영향 없음
- 확장 프로그램: 영향 없음
- Git 연동: 영향 없음
🤝 기여하기
버그 리포트
문제가 발생하면 다음 정보와 함께 이슈를 등록해주세요:
- macOS 버전:
sw_vers
- VSCode 버전:
code --version
- 문제 상황: 스크린샷 또는 동영상
- 재현 단계: 상세한 재현 방법
개발 참여
# 저장소 클론
git clone https://github.com/jongsik-code/korean-ime-fix-pjs.git
cd korean-ime-fix
# 의존성 설치
npm install
# 개발 모드 실행
npm run watch
# 테스트
F5 키로 Extension Development Host 실행
📄 라이선스
GPL 3.0
Copyright (c) 2025 Korean IME Fix by PJS Contributors
🔗 관련 링크
📞 지원
- 이슈: GitHub Issues
- 토론: GitHub Discussions
- 이메일: support@korean-ime-fix.dev
⭐ 이 확장 프로그램이 도움이 되었다면 GitHub에서 Star를 눌러주세요!
설치 완료 → VSCode 재시작 → 한글 입력 테스트 → 완료! ✅