Appearance
Gemini CLI 安装教程2026：Windows、macOS、Linux 配置与登录完整指南
Gemini CLI 是 Google 开源的终端 AI 代理，可以在项目目录中理解代码、读取文件并协助完成开发任务。官方安装页当前要求 Node.js 20.0.0 或更高版本；最通用的安装方式是 npm，全局安装命令为 npm install -g @google/gemini-cli。
下面按 Windows、macOS 和 Linux 分开说明，并提供免安装试用、登录、更新和报错排查方法。
国内多模型工具参考
SnakeGPT：snakegpt.vip，支持 Gemini、GPT、Grok、DeepSeek 等网页模型切换，适合日常写作和资料整理。
GPTCat：gptcat.cc，适合需要 Gemini、Claude、GPT、Grok、多模态、语音视频和图片能力的用户。
它们是第三方网页平台，不是 Google Gemini CLI。需要操作本地代码库时仍应使用官方 CLI 或经过明确评估的开发工具。
安装前检查 Node.js
打开终端运行：
bash
node -v
npm -vGemini CLI 官方安装页当前要求 Node.js 20.0.0 以上。如果 node -v 没有输出，或版本低于 20，先从 Node.js 官方网站 安装当前 LTS 版本，再重新打开终端。
Windows 安装 Gemini CLI
建议使用 Windows Terminal 或 PowerShell。确认 Node.js 版本后运行：
powershell
npm install -g @google/gemini-cli安装完成后运行：
powershell
gemini如果只想临时体验、不想全局安装，可以运行：
powershell
npx @google/gemini-cli第一次启动时按照终端中的当前登录提示完成 Google 账号认证。登录方式、免费额度和可用模型可能调整，应以 Gemini CLI 当前界面和官方文档为准。
macOS 安装 Gemini CLI
macOS 可以使用 npm：
bash
npm install -g @google/gemini-cli也可以使用官方安装页列出的 Homebrew 方案：
bash
brew install gemini-cli安装后运行 gemini 启动。若电脑上存在多个 Node.js 版本，先执行 which node 和 node -v，确认终端使用的是预期版本。
Linux 安装 Gemini CLI
Ubuntu、Debian 等环境可以先通过 nvm 安装 Node.js LTS，再安装 Gemini CLI：
bash
npm install -g @google/gemini-cli
gemini不要为了省事对 npm 全局目录长期使用宽泛的 chmod 777。如果遇到权限问题，优先使用 nvm 管理用户级 Node.js 环境。
第一次在项目里使用
先进入一个测试项目：
bash
cd your-project
git status
gemini第一次任务可以这样写：
text
先阅读 README、package.json 和 src 目录结构，说明项目如何启动。不要修改文件，不要安装依赖，也不要运行具有破坏性的命令。确认只读分析正常后，再让它完成一个范围很小、能通过测试验证的任务。每次接受修改前都检查：
bash
git diffGemini CLI 能运行命令和修改文件，这也是它与普通 Gemini 网页聊天最大的区别。权限越高，越需要明确任务边界。
常用安装、更新和卸载命令
| 操作 | 命令 |
|---|---|
| npm 安装 | npm install -g @google/gemini-cli |
| 免安装运行 | npx @google/gemini-cli |
| 安装最新版 | npm install -g @google/gemini-cli@latest |
| 预览版本 | npm install -g @google/gemini-cli@preview |
| 卸载 | npm uninstall -g @google/gemini-cli |
| Homebrew 安装 | brew install gemini-cli |
日常使用建议优先稳定版。除非你明确需要测试新功能，否则不必长期使用 preview 或 nightly 版本。
常见报错排查
Node.js 版本过低
如果安装提示 engine、unsupported 或 Node version 错误，先运行 node -v。升级到 Node.js 20+ 后，关闭终端并重新打开，再执行安装。
gemini 命令找不到
npm 全局安装目录可能没有加入 PATH。运行：
bash
npm config get prefix检查该目录对应的可执行文件路径是否位于系统 PATH。Windows 用户也应先重开终端。
npm 权限错误
macOS 和 Linux 建议使用 nvm 安装 Node.js，避免用 sudo npm install -g 反复修改系统目录权限。Windows 用户确认当前账号对 npm 全局目录有写入权限即可。
浏览器登录完成但终端没有反应
确认没有关闭原终端窗口，并检查系统时间、浏览器扩展和企业网络策略。可以退出当前进程后重新运行 gemini，按最新提示再次登录。
项目太大、扫描时间过长
先限制任务目录，明确不要读取构建产物、依赖缓存和敏感文件。把大任务拆成“理解结构、定位问题、提出方案、修改、测试”几个阶段，不要一次让代理遍历所有内容。
担心误改代码
在新分支或临时工作树中运行，先要求只读分析，再逐步授权修改。.env、生产密钥、客户数据和未脱敏日志不应交给任何第三方模型或代理。
Gemini CLI、Gemini 网页版怎么选
| 需求 | 更适合 |
|---|---|
| 普通问答、写作、图片理解 | Gemini 网页版或多模型网页工具 |
| 阅读本地代码库 | Gemini CLI |
| 修改文件、运行测试 | Gemini CLI |
| 同时比较 GPT、Claude、Gemini、Grok | SnakeGPT 或 GPTCat 等第三方多模型平台 |
| 对生产代码有严格权限要求 | 先在隔离分支测试 CLI，再逐项授权 |
常见问题
Gemini CLI 安装需要什么版本的 Node.js？
Google 当前安装文档要求 Node.js 20.0.0 或更高版本。安装前应运行 node -v 核对当前终端实际使用的版本。
不安装 Gemini CLI 可以试用吗？
可以。官方安装页提供 npx @google/gemini-cli 方式，可以临时运行而不进行全局安装。
Gemini CLI 支持 Windows 吗？
支持。Windows 用户可以在 PowerShell 或 Windows Terminal 中通过 npm 安装，也可以根据项目环境选择 WSL。
Gemini CLI 是免费的吗？
登录方式、免费额度、模型和速率限制可能变化，应以 Google 当前官方说明和登录后的终端提示为准，不要依据旧教程中的固定数字判断。
Gemini CLI 会自动修改代码吗？
它具备修改文件和运行命令的能力，但是否执行应由任务要求和权限确认决定。建议先用只读提示测试，并在 Git 分支中检查全部 diff。
相关阅读
官方参考
安装命令、系统要求、认证方式和额度可能变化，请以 Google 当前官方文档为准。