如何使用 npm 安裝 Gemini CLI：2025 年完整指南
由 Gemini 指南 於 2025/8/26 發布
npm 是安裝 Gemini CLI 最受歡迎和推薦的方式。在這份全面指南中，我們將帶您完成安裝過程，解決常見問題，並展示如何開始使用 Google 強大的 AI 命令列工具。
🚀 快速開始：使用 npm 安裝 Gemini CLI
前置要求
- Node.js（版本 18 或更高）
- npm（隨 Node.js 一起安裝）
- Google 帳戶（用於獲取 API 金鑰）
一鍵安裝
npm install -g @google/gemini-cli就這麼簡單！Gemini CLI 現在已經全域安裝到您的系統中了。
📋 詳細安裝步驟
第一步：驗證 Node.js 和 npm
首先，確保您有所需的版本：
node --version # 應該是 18.0.0 或更高
npm --version # 應該是 8.0.0 或更高第二步：安裝 Gemini CLI
npm install -g @google/gemini-cli這個命令的作用：
- 下載最新版本的 Gemini CLI
- 全域安裝（
-g標誌） - 使
gemini命令在系統範圍內可用
第三步：驗證安裝
gemini --version您應該看到類似這樣的輸出：
@google/gemini-cli/1.0.0 darwin-x64 node-v18.17.0
第四步：獲取您的 API 金鑰
- 造訪 Google AI Studio
- 使用您的 Google 帳戶登入
- 點擊「建立 API 金鑰」
- 複製產生的金鑰
第五步：設定您的 API 金鑰
macOS/Linux：
# 新增到您的 shell 配置檔案中
echo 'export GOOGLE_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc
# 或者對於 bash 使用者
echo 'export GOOGLE_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrcWindows：
# 設定環境變數
setx GOOGLE_API_KEY "your-api-key-here"
# 重新啟動終端或執行
refreshenv第六步：測試您的安裝
gemini "你好，Gemini CLI 正在工作！"🔧 替代安裝方法
使用 npx（無需全域安裝）
如果您不想全域安裝：
npx @google/gemini-cli "您的提示詞"使用 Yarn
如果您更喜歡使用 Yarn 而不是 npm：
yarn global add @google/gemini-cli使用 pnpm
如果您使用 pnpm：
pnpm add -g @google/gemini-cli🛠️ 常見問題故障排除
問題 1：權限被拒絕錯誤
錯誤： EACCES: permission denied
解決方案：
# 選項 1：使用 sudo（macOS/Linux）
sudo npm install -g @google/gemini-cli
# 選項 2：更改 npm 預設目錄（推薦）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @google/gemini-cli問題 2：命令未找到
錯誤： gemini: command not found
解決方案：
# 檢查是否已安裝
npm list -g @google/gemini-cli
# 如果需要，重新安裝
npm uninstall -g @google/gemini-cli
npm install -g @google/gemini-cli
# 檢查您的 PATH
echo $PATH
which gemini問題 3：API 金鑰未被識別
錯誤： API key not found
解決方案：
# 檢查環境變數是否設定
echo $GOOGLE_API_KEY
# 重新設定
export GOOGLE_API_KEY="your-actual-api-key"
# 立即測試
gemini "測試"問題 4：網路問題
錯誤： fetch failed 或 network error
解決方案：
# 檢查網路連線
ping google.com
# 嘗試不同的 DNS
nslookup aistudio.google.com
# 如果需要，使用 VPN
# 檢查防火牆設定📦 套件資訊
當前版本
npm view @google/gemini-cli version套件詳情
- 套件名：
@google/gemini-cli - 發行者： Google
- 授權： Apache-2.0
- 儲存庫： GitHub
相依性
npm view @google/gemini-cli dependencies🔄 更新 Gemini CLI
檢查更新
npm outdated -g @google/gemini-cli更新到最新版本
npm update -g @google/gemini-cli安裝特定版本
npm install -g @google/gemini-cli@1.0.0🎯 最佳實踐
1. 使用全域安裝
對於 CLI 工具，建議使用全域安裝：
npm install -g @google/gemini-cli2. 保持更新
定期更新確保您擁有最新功能和錯誤修正：
npm update -g @google/gemini-cli3. 保護您的 API 金鑰
永遠不要將 API 金鑰提交到版本控制：
# 好：使用環境變數
export GOOGLE_API_KEY="your-key"
# 壞：在腳本中硬編碼
gemini --key="your-key" "prompt"4. 使用版本控制
對於專案，考慮使用 .nvmrc 檔案：
# .nvmrc
18.17.0🚀 安裝後開始使用
要嘗試的第一個命令
# 基本互動
gemini "什麼是 Gemini CLI？"
# 檔案分析
gemini -f package.json "解釋這個 package.json 檔案"
# 程式碼審查
gemini -f src/ "審查這段程式碼的潛在問題"
# 產生文件
gemini -f src/ "為這個專案產生 README 文件"與您的工作流程整合
# VS Code 整合
# 新增到您的 VS Code tasks.json
{
"label": "程式碼審查",
"type": "shell",
"command": "gemini",
"args": ["-f", "${file}", "審查這段程式碼的 bug 和改進"],
"group": "build"
}
# Git 鉤子
# 新增到 .git/hooks/pre-commit
#!/bin/sh
git diff --cached | gemini "產生一個約定式提交訊息"📊 效能提示
最佳化速度
# 盡可能使用特定檔案而不是目錄
gemini -f src/main.js "審查這個檔案"
# 批次相關請求
gemini -f src/ "審查所有檔案的安全性問題、效能問題和程式碼品質"減少 API 使用
# 使用我們的模擬器進行測試
# 造訪：https://geminicli.net/simulator
# 使用我們的提示詞產生器最佳化命令
# 造訪：https://geminicli.net/prompt-generator🔍 進階設定
自訂設定檔案
建立 ~/.gemini/config.json：
{
"model": "gemini-2.5-pro",
"temperature": 0.7,
"maxTokens": 4096
}環境變數
# 設定預設模型
export GEMINI_MODEL="gemini-2.5-pro"
# 設定溫度
export GEMINI_TEMPERATURE="0.7"
# 設定最大權杖數
export GEMINI_MAX_TOKENS="4096"🎉 總結
使用 npm 安裝 Gemini CLI 簡單可靠。全域安裝使其在系統範圍內可用，官方 Google 套件確保您獲得最新功能和安全性更新。
要點：
- 使用
npm install -g @google/gemini-cli進行安裝 - 將 API 金鑰設定為環境變數
- 定期更新套件
- 使用我們的免費工具最佳化您的工作流程
準備開始了嗎？ 試用我們的線上模擬器 無需安裝即可體驗 Gemini CLI，或 按照我們的互動式安裝指南 獲取逐步說明。