docs: add documentation for seminar advice and npm path resolution and update background information

2026-05-28 05:46:05 +00:00
parent 91527fd56d
commit 7a396ed97a
4 changed files with 229 additions and 1 deletions
@@ -0,0 +1,58 @@
+# npm global 패키지 경로 분리 문제 해결
+
+## 문제
+
+`npm install -g @google/gemini-cli@latest` 설치 후 `gemini` 명령어가 실행되지 않음.
+
+```
+zsh: command not found: gemini
+```
+
+## 원인
+
+**Hermes AI Agent**가 자체 Node.js를 `~/.hermes/node/`에 번들링하여 설치하면서,
+npm의 global prefix가 해당 경로(`~/.hermes/node`)로 설정되어 있었음.
+
+그 결과 npm global 패키지도 `~/.hermes/node/bin/`에 설치되었으나,
+이 경로가 `$PATH`에 포함되어 있지 않아 명령어를 찾지 못함.
+
+```
+; node bin location = /home/godopu16/.hermes/node/bin/node   ← Hermes 번들 Node
+; npm global prefix  = /home/godopu16/.hermes/node           ← prefix 오염
+```
+
+## 해결
+
+### 1. npm global 전용 디렉토리 생성 및 prefix 변경
+
+```zsh
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+```
+
+### 2. `~/.zshrc`에 PATH 추가
+
+```zsh
+export PATH="$HOME/.npm-global/bin:$PATH"
+```
+
+### 3. gemini-cli 재설치
+
+```zsh
+npm install -g @google/gemini-cli@latest
+```
+
+### 4. 적용
+
+```zsh
+source ~/.zshrc
+gemini --version
+```
+
+## 결과
+
+| 항목 | 변경 전 | 변경 후 |
+|------|---------|---------|
+| npm global prefix | `~/.hermes/node` | `~/.npm-global` |
+| gemini 바이너리 위치 | `~/.hermes/node/bin/gemini` | `~/.npm-global/bin/gemini` |
+| 명령어 동작 | ❌ `command not found` | ✅ 정상 실행 |