Skip to content

Troubleshooting ko

Jump to bottom
Kevin Kim edited this page Aug 16, 2025 · 1 revision

Troubleshooting

Nimf 사용 중 발생할 수 있는 일반적인 문제들과 해결 방법을 안내합니다.

🔍 진단 도구

1. 기본 상태 확인

# Nimf 프로세스 확인
ps aux | grep nimf

# 환경 변수 확인
echo "GTK_IM_MODULE: $GTK_IM_MODULE"
echo "QT_IM_MODULE: $QT_IM_MODULE"
echo "XMODIFIERS: $XMODIFIERS"

# 입력 모듈 파일 확인
ls -la /usr/lib/*/gtk-*/*/immodules/im-nimf.so
ls -la /usr/lib/*/qt*/plugins/platforminputcontexts/*nimf*

2. 디버그 모드 실행

# Nimf 디버그 모드로 실행
killall nimf
G_MESSAGES_DEBUG=nimf nimf --debug

# 별도 터미널에서 애플리케이션 실행
GTK_IM_MODULE=nimf gedit
QT_IM_MODULE=nimf kate

🚫 일반적인 문제들

1. 입력기가 전혀 작동하지 않는 경우

증상

  • 한글 입력이 전혀 되지 않음
  • Ctrl+Space를 눌러도 반응 없음

해결 방법

1단계: 환경 변수 확인

# ~/.bashrc 또는 ~/.zshrc에 추가
export GTK_IM_MODULE=nimf
export QT_IM_MODULE=nimf
export XMODIFIERS=@im=nimf

# 설정 적용
source ~/.bashrc

2단계: im-config 설정 (Ubuntu/Debian)

im-config -n nimf

3단계: Nimf 재시작

killall nimf
nimf &

2. 특정 애플리케이션에서만 작동하지 않는 경우

GTK 애플리케이션 (Firefox, LibreOffice, gedit 등)

# GTK 입력 모듈 확인
ls /usr/lib/*/gtk-*/*/immodules/im-nimf.so

# GTK 입력 모듈 캐시 업데이트
sudo gtk-query-immodules-2.0 --update-cache
sudo gtk-query-immodules-3.0 --update-cache

# 애플리케이션 실행
GTK_IM_MODULE=nimf firefox

Qt 애플리케이션 (Kate, Konsole, VLC 등)

# Qt 입력 모듈 확인
ls /usr/lib/*/qt*/plugins/platforminputcontexts/*nimf*

# Qt 환경 변수 설정
export QT_IM_MODULE=nimf
export QT_QPA_PLATFORMTHEME=qt5ct  # 필요시

# 애플리케이션 실행
kate

Electron 애플리케이션 (VS Code, Discord 등)

# Electron 애플리케이션용 설정
export GTK_IM_MODULE=nimf
export XMODIFIERS=@im=nimf

# VS Code 실행
code --enable-features=UseOzonePlatform --ozone-platform=wayland

3. ibus와의 충돌 문제

증상

  • 입력기가 불안정하게 작동
  • 두 개의 입력기가 동시에 실행

해결 방법

방법 1: ibus 완전 제거 (권장)

sudo apt purge ibus
sudo apt autoremove

방법 2: ibus-daemon 비활성화

sudo mv /usr/bin/ibus-daemon /usr/bin/ibus-daemon.bak

방법 3: ibus 서비스 비활성화

systemctl --user mask ibus.service
systemctl --user stop ibus.service

4. Wayland에서의 문제 (v1.4.0+ 대폭 개선)

증상

  • Wayland 세션에서 입력기가 작동하지 않음
  • 일부 애플리케이션에서만 작동

해결 방법 (v1.4.0+ 개선사항)

1단계: 향상된 Wayland 지원 확인

echo $XDG_SESSION_TYPE  # wayland 출력 확인
nimf --version  # 1.4.0+ 버전 확인

2단계: 자동 Wayland 감지 (v1.4.0+)

# Nimf 1.4.0+에서는 Wayland를 자동으로 감지하고 최적화됨
# 대부분의 경우 추가 설정 불필요

# 기본 환경 변수만 설정
export GTK_IM_MODULE=nimf
export QT_IM_MODULE=nimf
export XMODIFIERS=@im=nimf

3단계: 고급 Wayland 설정 (필요시)

# 특정 애플리케이션에서 문제가 있는 경우
export WAYLAND_DISPLAY=wayland-0
export GDK_BACKEND=wayland
export QT_QPA_PLATFORM=wayland

5. 한글 입력이 깨지는 경우

증상

  • 한글이 조합되지 않고 자모가 분리됨
  • 특정 자음이나 모음이 입력되지 않음

해결 방법

1단계: 폰트 확인

# 한글 폰트 설치
sudo apt install fonts-noto-cjk fonts-nanum

2단계: 로케일 설정

# 로케일 확인
locale

# 한국어 로케일 설정
sudo locale-gen ko_KR.UTF-8
export LANG=ko_KR.UTF-8

3단계: libhangul 설정 확인

# libhangul 데이터 확인
ls -la /usr/share/libhangul/

6. Qt6 애플리케이션에서 입력이 안 되는 경우 (v1.4.0+ 개선)

증상

  • Qt6 기반 애플리케이션에서만 한글 입력 불가
  • Qt5 애플리케이션은 정상 작동

해결 방법

1단계: Qt6 입력 모듈 확인

ls /usr/lib/*/qt6/plugins/platforminputcontexts/
# libnimfqt6.so 파일이 있는지 확인

2단계: Qt6 환경 변수 설정

export QT_IM_MODULE=nimf
export QT6_IM_MODULE=nimf

3단계: 향상된 Qt6 호환성 (v1.4.0+)

# Nimf 1.4.0+에서는 Qt6 호환성이 크게 개선됨
# 대부분의 Qt6 애플리케이션에서 추가 설정 없이 작동

# 문제가 지속되는 경우 nimf 재시작
killall nimf
nimf &

7. 시스템 트레이 아이콘이 보이지 않는 경우

GNOME

# GNOME Shell 확장 설치
# "TopIcons Plus" 또는 "AppIndicator and KStatusNotifierItem Support"

KDE Plasma

# 시스템 트레이 설정 → 항목 → Nimf 활성화

XFCE

# 패널 → 항목 추가 → 알림 영역

🔧 고급 문제 해결

1. 설정 파일 손상

# 설정 파일 백업 및 초기화
mv ~/.config/nimf ~/.config/nimf.backup
killall nimf
nimf &

2. 라이브러리 의존성 문제

# 라이브러리 의존성 확인
ldd /usr/lib/*/gtk-*/*/immodules/im-nimf.so
ldd /usr/lib/*/qt*/plugins/platforminputcontexts/libnimfqt*.so

# 누락된 라이브러리 설치
sudo apt install --fix-missing

3. 권한 문제

# 설정 파일 권한 확인
ls -la ~/.config/nimf/

# 권한 수정
chmod 755 ~/.config/nimf/
chmod 644 ~/.config/nimf/*

4. 메모리 누수 문제

# 메모리 사용량 확인
ps aux | grep nimf | awk '{print $6}'

# Nimf 재시작
killall nimf
nimf &

🆕 v1.4.0 특화 문제 해결

1. 모듈형 패키지 관련 문제

다국어 입력이 안 되는 경우

# nimf-i18n 패키지 설치 확인
dpkg -l | grep nimf-i18n  # Debian/Ubuntu
rpm -qa | grep nimf-i18n  # Fedora/openSUSE

# 설치되지 않은 경우
sudo apt install nimf-i18n  # Debian/Ubuntu
sudo dnf install nimf-i18n  # Fedora

2. GTK4 애플리케이션 문제

GTK4 앱에서 입력이 안 되는 경우

# GTK4 IM 모듈 확인
ls /usr/lib/*/gtk-4.0/*/immodules/im-nimf.so

# 환경 변수 확인
echo $GTK_IM_MODULE  # nimf 출력되어야 함

# GTK4 IM 모듈 캐시 업데이트
sudo gtk-query-immodules-4.0 --update-cache

3. ARM64 플랫폼 특화 문제

ARM64에서 성능 저하

# ARM64 최적화 빌드 확인
file /usr/bin/nimf  # ARM aarch64 출력 확인

# 메모리 사용량 최적화
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf

📊 성능 최적화 (v1.4.0+ 개선)

1. 향상된 시작 시간 (v1.4.0+)

# 1.4.0+에서는 시작 시간이 대폭 개선됨
# 추가 최적화가 필요한 경우에만:

# 불필요한 입력 엔진 비활성화
# ~/.config/nimf/nimf.conf 편집
[Engines]
enabled-engines=nimf-libhangul,nimf-system-keyboard

2. 메모리 효율성 개선 (v1.4.0+)

# 모듈형 구조로 메모리 사용량 최적화됨
# nimf-i18n을 사용하지 않으면 자동으로 메모리 절약

# 추가 최적화
# nimf-settings → 후보 창 → 최대 항목 수 조정

3. CPU 사용량 최적화

# 자동 완성 기능 비활성화 (필요시)
# nimf-settings → 한국어 → 자동 완성 비활성화

🐛 버그 리포트

문제가 계속 발생하는 경우 다음 정보와 함께 버그 리포트를 작성해주세요:

수집할 정보

# 시스템 정보
uname -a
lsb_release -a

# Nimf 버전
nimf --version

# 환경 변수
env | grep -E "(GTK_IM|QT_IM|XMODIFIERS|LANG|LC_)"

# 프로세스 정보
ps aux | grep nimf

# 로그 수집
G_MESSAGES_DEBUG=nimf nimf --debug 2>&1 | tee nimf-debug.log

버그 리포트 제출

📚 관련 문서

Clone this wiki locally