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의 IME composition 이벤트 처리 버그
- macOS Sequoia와 한글 IME 간의 호환성 문제
- composition 이벤트가 예상과 다르게 분리되어 처리됨
해결 방법
IME Composition 이벤트 오버라이드
compositionstart, compositionupdate, compositionend 이벤트 래핑- 한글 자모 조합 로직 개선
VSCode 에디터 설정 최적화
accessibilitySupport 활성화- 자동완성 기능 조정으로 IME 간섭 방지
Monaco Editor 특화 처리
- Monaco Editor의 IME 관련 설정 강제 적용
- 한글 문자 렌더링 최적화
핵심 기술
// 한글 조합 완료 대기 로직
if (state.compositionData.length === 1) {
compositionTimer = setTimeout(() => {
const timeDiff = Date.now() - currentState.lastUpdateTime;
if (timeDiff > 150) {
// 강제 조합 완료 처리
const compositionEndEvent = new CompositionEvent('compositionend', {
data: currentState.compositionData,
bubbles: true,
cancelable: true
});
event.target.dispatchEvent(compositionEndEvent);
}
}, 200);
}
🖥 지원 환경
운영체제
- ✅ 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 재시작 → 한글 입력 테스트 → 완료! ✅
