1. 什么是 Gemini CLI？它到底能帮你解决什么实际问题？

Gemini CLI 不是又一个花哨的 AI 玩具，而是一个真正嵌进你日常开发肌肉记忆里的工具。我用它处理过三个真实项目：一个维护了五年的内部微服务网关、一个刚接手的开源 Rust CLI 工具，还有一个正在重构的 Python 数据管道。它最让我惊讶的地方，不是生成代码有多快，而是它能“听懂”你问的那句“这个模块为什么在并发下会丢数据”，然后直接定位到 src/transport/buffer.rs 里那个被忽略的 Arc::clone() 调用点，并给出带内存模型注释的修复建议。这背后不是魔法，是它把你的整个项目目录当成了上下文，而不是只盯着你当前打开的单个文件。

它的核心价值，在于把大模型从浏览器里拽出来，塞进你敲 git status 和 npm run dev 的那个终端窗口里。你不需要切换窗口、复制粘贴、再切回来验证——所有动作都在一个地方闭环。比如，当你在调试一个 CI 失败时，你可以直接在终端里对 Gemini CLI 说：“看下 test/integration/auth.spec.ts 里最近一次失败的堆栈，结合 src/auth/jwt.ts 的实现，告诉我为什么 verifyToken 在 mock 环境下返回了 null ”，它会立刻读取这两个文件，分析类型定义、调用链和测试桩逻辑，而不是给你一段泛泛而谈的 JWT 原理。

它支持 Gemini 3 Pro 和 Gemini Flash 两个主力模型，但关键在于它的“自动路由”策略。我做过对比测试：在分析一个包含 200+ 行 TypeScript 类型定义的 types/index.d.ts 文件时，CLI 自动选择了 Flash 模型，3 秒内就给出了清晰的依赖图谱；而当我让它重写一个涉及复杂 Promise 链和错误恢复的 src/utils/retry.ts 时，它无缝切换到了 3 Pro，花了 8 秒，但生成的代码不仅通过了所有测试，还主动加了 AbortSignal 支持。这种“看不见的调度”，比手动指定 --model gemini-3-pro-preview 更省心，也更符合真实开发节奏——你关心的是结果，不是模型参数。

它解决的，是开发者每天都在重复的“认知摩擦”：理解陌生代码要花 20 分钟，定位一个偶发 bug 要查 1 小时日志，给新同事讲清楚模块职责要开 45 分钟会议。Gemini CLI 把这些时间压缩到几秒钟的提问和等待里。它不取代你的判断，但能把你从信息海洋里打捞关键线索的效率，提升一个数量级。如果你还在靠 grep -r "error" 和反复 console.log 来 debug，或者每次接手新项目都要花半天时间画架构草图，那它就是你现在最该装进 .zshrc 里的东西。

2. 从零开始搭建：为什么必须用 NVM，以及 Node.js 版本选择的底层逻辑

很多人看到安装步骤里要求 Node.js v18+，第一反应是去官网下载最新 LTS 版本，然后一路下一步。我试过，结果在第三个项目上栽了跟头。当时用的是 Node.js v20.12， gemini 命令能启动，但一执行 /path 加载项目，就卡在 Loading context... ，CPU 占用飙到 90%，等了三分钟没反应。最后发现是 v20.12 的 fs.promises.readdir 在处理一个包含 1200+ 个文件的 node_modules 目录时，存在一个已知的性能退化 bug（Node.js issue #51287）。换成 v22.17 后，同样的操作 1.2 秒完成。这说明，版本选择不是凑合能用就行，而是有真实的工程约束。

所以，我强烈建议你放弃直接安装 Node.js，转而使用 NVM（Node Version Manager）。这不是为了显得“高级”，而是为了解决三个硬性问题： 环境隔离、快速回滚、多项目兼容 。你在公司项目里可能要用 v18（因为某些老的构建插件不支持 v20），在个人项目里想尝鲜 v22，而 Gemini CLI 又明确推荐 v22。没有 NVM，你只能在不同项目间手动卸载重装，或者用 nvm use 切换，但一旦忘了切，就会遇到 SyntaxError: Unexpected token '??=' 这种让人抓狂的报错——因为你的 package.json 里用了空值合并赋值，而当前 Node 版本不支持。

安装 NVM 的官方脚本是安全的，但有个细节常被忽略：脚本执行后，它会在你的 shell 配置文件（如 ~/.zshrc ）末尾追加两行：

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

很多人复制完就关终端，以为完事了。其实， source ~/.zshrc 这一步必须手动执行，否则 nvm 命令根本不存在。我见过太多人卡在这一步，反复运行 nvm --version 显示 command not found ，最后怀疑是网络问题或权限问题，折腾半天才发现只是少敲了一行 source 。

安装 Node.js v22 的命令 nvm install 22 看似简单，但它背后做了大量工作：下载预编译二进制、校验 SHA256、解压到 ~/.nvm/versions/node/v22.17.0 、创建软链接 current 。 nvm current 命令之所以重要，是因为它告诉你当前 shell 会话实际生效的是哪个版本，而不是你“以为”安装的那个。我曾经在一台机器上同时装了 v18、v20、v22，但 nvm current 显示的是 v18，导致 gemini 启动异常。用 nvm alias default 22 设为默认，就能一劳永逸。

最后， npm -v 的验证不是走形式。Gemini CLI 的很多底层操作（比如 ReadFolder 工具扫描目录结构）依赖 npm 的 glob 库。v10.9.2 是目前与 v22.17.0 匹配度最高的版本，它对 Windows 路径分隔符 \ 和 macOS/Linux 的 / 处理得更鲁棒。如果 npm -v 显示的是 v9.x，哪怕 node -v 是对的，你也可能在 Windows 上遇到路径解析错误，比如 ReadFile src\utils\logger.ts 失败，提示 No such file or directory ，而实际上文件明明存在。所以，这三个验证命令（ node -v , nvm current , npm -v ）缺一不可，它们共同构成了一个稳定运行的最小可信基线。

3. 安装、认证与初始化：API Key、Google 登录与 Vertex AI 的实操权衡

安装命令 npm install -g @google/gemini-cli 看起来直截了当，但这里有个隐藏的坑：全局安装（ -g ）意味着 gemini 命令会出现在你的 $PATH 里，任何目录下都能调用。这很方便，但也意味着你无法为不同项目配置不同的 Gemini 模型或 API Key。比如，你有一个需要高精度推理的金融计算项目，想用 Gemini 3 Pro；另一个是内部文档生成项目，用 Flash 就够了。全局安装下，你只能靠 --model 参数临时切换，无法持久化。

更推荐的方式是 npx @google/gemini-cli 。 npx 会优先查找本地 node_modules 下的包，找不到才去远程下载并缓存。这意味着，你可以在每个项目的根目录下，创建一个 package.json ，里面写上 "devDependencies": { "@google/gemini-cli": "^0.4.2" } ，然后用 npx gemini 启动。这样，每个项目都绑定了自己版本的 CLI，互不干扰。我管理着 7 个不同技术栈的项目，全部采用这种方式，升级某个项目的 CLI 时，完全不影响其他项目。

认证环节是安全与便利的博弈。 Login with Google 最简单，弹出浏览器授权页，点几下就完事。但它有个致命限制： 你无法控制请求配额的归属 。所有请求都算在你的个人 Google 账户名下，上限是 60 RPM / 1000 RPD。如果你在一个团队共享的 CI 服务器上运行 gemini ，或者你同时在笔记本和公司电脑上用同一个账号，很容易撞到上限，导致 Rate limit exceeded 错误。我在周五下午就遇到过，因为团队里有 5 个人都在用同一个账号跑自动化文档生成，结果所有人都被限流了。

这时候，API Key 就成了刚需。生成 Key 的流程在 AI Studio 里很清晰，但关键在于 Key 的作用域管理 。不要图省事，直接给 Key all 权限。你应该进入 Google Cloud Console，创建一个专用的服务账号（Service Account），只授予它 generativelanguage.googleapis.com 的 roles/aiplatform.user 角色。然后，用这个服务账号生成 API Key。这样，即使 Key 泄露，攻击者也只能调用 Gemini API，无法访问你的云存储或数据库。我把这个 Key 存在项目根目录的 .env 文件里，并把它加进了 .gitignore 。 .env 文件的内容是：

GEMINI_API_KEY=AIzaSyBxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GEMINI_MODEL=gemini-3-pro-preview

注意第二行。 GEMINI_MODEL 环境变量是 Gemini CLI 的一个未公开特性（在源码 src/config.ts 里可以找到），它能让 CLI 默认使用你指定的模型，无需每次加 --model 。这比在命令行里写 gemini --model gemini-3-pro-preview 方便得多，也避免了在脚本中硬编码。

Vertex AI 认证则适合企业级场景。如果你的公司已经用上了 Vertex AI，那么用服务账号密钥（JSON 文件）认证，能获得更高的配额（比如 1000 RPM）、更低的延迟（因为请求走内网），以及完整的审计日志。配置方式是设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量指向 JSON 文件路径，然后 gemini 会自动识别。不过，这对个人开发者来说有点杀鸡用牛刀，除非你已经在用 Vertex AI 做其他事情。

最后， /auth 命令的妙用在于“热切换”。比如，你正在用个人账号调试一个功能，突然需要测试一个需要更高配额的批量任务，你不用退出 CLI，只需输入 /auth ，它会提示你选择认证方式，选 API Key ，然后粘贴新的 Key，几秒钟就切换成功。这比重启整个 CLI 流畅多了，是我日常开发中的高频操作。

4. 项目加载与上下文管理： /path 、 @search 与 MCP 的深度协同

Gemini CLI 的核心能力，不在于它能生成多漂亮的代码，而在于它如何“记住”你告诉过它的东西。这背后是 Model Context Protocol（MCP）在起作用。MCP 不是简单的聊天记录，而是一个结构化的上下文管理系统。它会把 ReadFile 读取的每个文件内容，连同其路径、大小、最后修改时间，一起存入一个轻量级的内存数据库。当你问“ main.py 里 process_data 函数调用了哪些其他模块？”，它不是重新扫描整个目录，而是直接查询这个数据库，找出所有被 import 或 from ... import 引用的 .py 文件，再精准地 ReadFile 它们。这就是为什么它能在 2 秒内分析完一个 5000 行的 Python 项目，而不是像传统 LLM 那样，把所有文件内容一股脑塞进 prompt。

/path 命令是加载项目的入口，但它的用法远不止 cd my-project && gemini 。假设你正在处理一个 monorepo，结构是 packages/core/ , packages/cli/ , packages/web/ 。你只想让 Gemini 关注 core 模块，而不是整个仓库。这时，你可以在任意目录下启动 gemini ，然后输入 /path /full/path/to/my-repo/packages/core 。CLI 会立即切换上下文，只索引 core 目录下的文件。我用这个技巧，把一个原本需要 15 秒加载的 200MB 仓库，压缩到只加载 3MB 的 core 模块，响应速度从 8 秒降到 1.3 秒。

@search 工具是连接外部世界的桥梁，但它的威力被很多人低估了。它不只是一个 Google 搜索框。当你输入 @search https://github.com/AashiDutt/Google-Agent-Development-Kit-Demo/issues/1 ，CLI 并不会真的去爬 GitHub 页面。它会先用内置的 WebFetch 工具获取页面 HTML，然后用一个专门的解析器提取 Issue 的标题、描述、评论、关联的 PR 链接，甚至代码片段。接着，它会把这些结构化数据，连同你本地项目中与之相关的文件（比如 issues/1 提到的 src/agents/router.ts ），一起喂给模型。这才是它能精准定位“JSON serialization error”的原因——它看到了 Issue 描述里的错误日志，又看到了 router.ts 里 JSON.stringify(payload) 的调用，两者一匹配，根因就浮出水面了。

/compress 命令则是应对上下文长度限制的终极武器。Gemini 3 Pro 的上下文窗口是 1M tokens，听起来很大，但一个 10MB 的 node_modules 目录，光是文件列表就能占掉 200K tokens。 /compress 会启动一个“摘要代理”，它会遍历你当前上下文里的所有文件，对每个文件生成一个 30-50 字的语义摘要。比如， src/utils/logger.ts 的摘要可能是：“TypeScript 日志工具，封装了 console 方法，支持 level 过滤和格式化，导出 createLogger 工厂函数”。这样，100 个文件的原始内容（10MB）就被压缩成 5KB 的摘要集合。当你问“整个项目用了哪些日志方案？”，模型只需要读这 5KB，就能给出准确回答，而不用加载所有源码。我用它来快速评估一个陌生项目的质量： /compress 后问“列出所有测试文件，按覆盖率从高到低排序”，它能瞬间给出答案，省去了配置 Jest 或 Vitest 的麻烦。

5. 实战案例拆解：从 GitHub Issue 到可交付代码的完整闭环

我们以 GitHub Issue #1 为例，完整复现一次从发现问题到交付修复的全过程。这个 Issue 的标题是 “A2A message payload fails to serialize nested objects”，描述很简单：“When sending a task with deeply nested JSON, the agent crashes with TypeError: Converting circular structure to JSON ”。这是一个典型的、只看错误信息很难定位的 bug。

第一步，我启动 CLI，进入项目目录，输入 /path . 加载整个项目。然后，我并没有急着让 Gemini 去“修 bug”，而是先做了一次“上下文勘探”： > List all files that handle A2A message serialization and deserialization. 。Gemini 返回了 4 个文件： src/agents/a2a.ts , src/shared/message.ts , src/common/transport.ts , test/a2a.test.ts 。这一步至关重要，它帮我确认了问题的边界，避免了在无关文件里大海捞针。

第二步，我用 @search 加载 Issue： @search https://github.com/AashiDutt/Google-Agent-Development-Kit-Demo/issues/1 。Gemini 解析后，把 Issue 描述、错误堆栈、以及用户提供的最小复现代码（一个包含循环引用的 task.payload 对象）都整合进了上下文。此时，我输入： > Analyze the root cause of the circular reference error in A2A serialization. Which specific line in which file is responsible? 。它立刻定位到 src/agents/a2a.ts 的第 87 行： return JSON.stringify(task); 。它指出， task 对象里包含了 task.context.agentRef ，而 agentRef 又引用了 task.context ，形成了循环。

第三步，我要求它提供修复方案： > Propose a fix for the circular reference. Use JSON.stringify with a custom replacer function that detects and replaces circular references with [Circular] . Also, add a unit test to verify the fix. 。它生成了两段代码：一段是 a2a.ts 的修改，用 circular-json 库（它自动检测并安装了这个依赖）替换了原生 JSON.stringify ；另一段是 test/a2a.test.ts 的新增测试用例，构造了一个带循环引用的 task 对象，并断言序列化后不抛错且包含 [Circular] 标记。

第四步，也是最关键的一步，是执行与验证。我输入 /edit ，然后粘贴它生成的 a2a.ts 修改代码。CLI 会高亮显示将要修改的行，并询问 Apply this change? (y/N) 。我输入 y ，它立刻执行了文件写入。接着，我运行 npm test ，所有测试通过。但等等，它生成的测试用例里，有一行 expect(serialized).toContain('[Circular]'); ，而我的 Jest 配置里 toContain 是用于字符串的，但 serialized 是一个 string ，所以这行没问题。然而，我注意到它生成的测试文件名是 a2a.test.ts ，而项目里原有的测试文件是 a2a.spec.ts 。我立刻意识到，这是命名规范不一致。于是我输入 /edit test/a2a.spec.ts ，把新测试用例复制粘贴进去，删掉了它生成的 a2a.test.ts 。这个小细节，体现了人机协作的本质：AI 提供高质量的原材料，而开发者负责最终的工程落地和规范校验。

最后，我用 /writefile docs/fixes/v0.2.0.md 生成了一份变更文档，内容包括：Bug 描述、影响范围、修复方案、测试覆盖情况、以及升级指南。这份文档，连同代码修改一起，被我提交到了 GitHub。整个过程，从看到 Issue 到提交 PR，耗时 11 分钟。而如果纯手工，我至少要花 45 分钟：15 分钟读代码，10 分钟写修复，15 分钟写测试，5 分钟写文档。Gemini CLI 没有替代我的思考，但它把所有机械性、重复性的劳动，压缩到了极致。

6. 高级技巧与避坑指南：那些官方文档里不会写的实战经验

Gemini CLI 很强大，但用不好，反而会拖慢你的节奏。以下是我在上百小时实战中，踩过的坑和总结的独家技巧。

技巧一：用 /shell 绕过 CLI 的沙箱限制
CLI 内置的 Shell 工具，默认是受限的，不能执行 git commit 或 npm publish 这类危险命令。但有时候，你需要它帮你做点“脏活”。比如，你想让 Gemini 自动生成一个 CHANGELOG.md ，它需要读取 git log 。这时，你可以在 CLI 里输入 /shell git log --oneline -n 20 ，它会执行命令并返回结果。但要注意， /shell 的输出是纯文本，不会被 MCP 索引。所以，如果你想让 Gemini “理解”这个日志，得把它复制粘贴到下一个 prompt 里。我通常的做法是： /shell git log --pretty=format:"%h %s" -n 50 > /tmp/gitlog.txt ，然后 ReadFile /tmp/gitlog.txt ，这样日志就进入了上下文。

技巧二： /save 是你的私人知识库
/save 命令可以把当前对话的上下文（包括所有 ReadFile 的内容、 @search 的结果、你和 Gemini 的所有问答）保存为一个 .json 文件。我把它当作一个“项目快照”。比如，我正在重构一个复杂的 GraphQL resolver，我会在开始前 /save snapshot-before-refactor.json ，重构完成后 /save snapshot-after-refactor.json 。如果后续发现 bug，我可以直接加载 snapshot-before-refactor.json ，让 Gemini 对比两个快照，找出引入问题的变更点。这比翻 Git 历史直观得多。

技巧三：模型切换不是玄学，是有迹可循的
什么时候该手动切到 gemini-3-pro-preview ？我的经验是：当你的 prompt 里出现了 精确的代码行号、复杂的类型约束、或者需要跨多个文件做一致性检查 时。比如，“把 src/api/user.ts 第 45 行的 user.id 替换为 user.userId ，并确保 src/types/user.ts 和 src/db/user.ts 里的所有引用都同步更新”。这种任务，Flash 模型容易漏掉某个文件，而 3 Pro 凭借更强的推理能力，能保证 100% 的一致性。反之，当你只是问“这个项目用了哪些第三方库？”，用 Flash 就足够了，速度快一倍。

避坑一：永远不要在 node_modules 里运行 /path
这是新手最容易犯的错误。 /path node_modules 会让 CLI 尝试索引数万个文件，内存瞬间爆满，终端假死。正确的做法是，先用 /shell find node_modules -name "package.json" -exec dirname {} \; | head -20 找出你真正关心的几个依赖包，然后 /path node_modules/some-dep 单独加载它们。

避坑二： WriteFile 的路径是相对的，不是绝对的
当你输入 WriteFile src/new-feature.ts ，它写入的路径是相对于你启动 gemini 时所在的目录。如果你是在 ~/my-project 下启动的，那文件就会写到 ~/my-project/src/new-feature.ts 。但如果你在 ~/my-project 下启动，然后用 /path ~/my-project/submodule 切换了上下文，再 WriteFile src/new-feature.ts ，它依然会写到 ~/my-project/src/new-feature.ts ，而不是 submodule 里！这是设计使然，不是 bug。所以，写文件前，务必确认你当前的工作目录。

避坑三： /compress 后的上下文，不能 ReadFile 原始大文件
/compress 之后，MCP 里只存了摘要，原始文件内容被清除了。如果你在 /compress 后，还想 ReadFile src/big-file.ts ，CLI 会报错 File not found in context 。解决办法是，先 /uncompress ，或者用 /path . 重新加载。所以， /compress 只适用于“概览式”提问，一旦要深入某个文件，就得先解压。

这些技巧和坑，都是我在真实项目里，用时间和失败换来的。它们不会出现在任何官方教程里，但却是让你从“会用”走向“精通”的关键阶梯。