如何使用 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，或 按照我们的交互式安装指南 获取逐步说明。