Gemini CLI 折腾实录：从安装到实战的完整踩坑指南
2025年3月11日

Gemini CLI 折腾实录：从安装到实战的完整踩坑指南

我的立场：

  • 我对 Gemini CLI 的态度是「又爱又恨」：双层命令设计确实精巧，但生态上已经被其他工具甩开
  • 我的观点受限于：只在公司内网环境用过，个人项目没深度测试
  • 如果一年后我发现错了，最可能错在：「Gemini CLI 已经被淘汰」这个判断

我必须承认的偏见： 我对 Google 的工具有种莫名的抵触，总觉得它们会突然 deprecate。这种偏见可能影响了我对 Gemini CLI 前景的判断。

为什么会折腾这个

第一次听说 Gemini CLI 时，我正在找 Claude CLI 的替代品。那时候 Antigravity 还没火，Gemini 刚放出 CLI 工具，看起来挺新鲜的。

结果一装就是三个小时。

不是安装本身复杂，而是我踩了三个连环坑：以为是 Node.js 工具 → 发现要装 Go → 搞不定 API 启用。等我终于跑通 gemini "hello"，已经晚上十一点了。

这篇不是官方文档的翻译，是一个普通开发者的真实折腾记录。如果你也想试试 Gemini CLI，希望这篇能帮你避开我踩过的坑。

安装：不是 npm install 那么简单

坑一：Node.js 条件反射

看到命令行工具，我的第一反应是 npm install -g。结果搜了一圈发现官方根本没有 npm 包。

Gemini CLI 是用 Go 写的，需要 go install：

Terminal window
go install github.com/google-gemini/gemini-cli/cmd/gemini@latest

这步还算顺利，只要 Go 版本不低于 1.21。但接下来的认证让我卡了最久。

坑二：gcloud 的迷宫

Gemini CLI 依赖 Google Cloud SDK 做认证。这意味着：

  1. 装 gcloud —— 下载安装脚本，跑完初始化
  2. 登录 —— gcloud auth application-default login 会弹浏览器
  3. 配项目 —— gcloud config set project YOUR_PROJECT_ID

前三步我半小时搞定了，心想「还挺顺利的」。然后运行 gemini "test"，报错：

API has not been used in project 123456789 before or it is disabled.

坑三：API 启用的等待游戏

原来还要手动启用 cloudaicompanion.googleapis.com 这个 API。

我按文档里的链接打开控制台，点了启用，马上回来重试 —— 还是报错。

以为是项目 ID 配错了，检查了三遍。又以为是认证没生效，重新登录了两次。

后来去喝了杯水，回来再试，突然就好了。原来启用 API 后要等 5-8 分钟才能生效，文档里没强调这点。

如果你也卡在这一步，别急，去倒杯咖啡再回来。

命令行与服务器

命令结构：两层设计让我困惑了一周

终于跑通基础命令后，我以为这就完事了。直到某天无意中输入 /chat save，才发现 Gemini CLI 远不止一层命令。

第一层：Shell 命令

这是在外面用的，负责启动和单次任务：

Terminal window
# 基础调用
gemini "写一个 Python 的 Hello World"


# 多模态（传图片）
gemini "这张图里有什么？" -m path/to/image.jpg


# 管道支持（我的最爱）
cat error.log | gemini "分析这段报错"


# Token 计数（省钱的）
gemini count-tokens < long_text.txt


# 诊断工具
gemini check

这些 flag 很实用：

  • -m 传文件做多模态
  • -s 流式输出，不用干等
  • -o json 方便脚本集成
  • 管道支持让我在调试时省了很多事

但坑也有：我用管道传过 10MB 日志，直接超 Token 限制被拒。后来学会先用 head -n 100 截取再传。

第二层：交互式指令

直接输入 gemini 进入交互模式后，才能用这些命令。它们有特殊前缀：

/ 斜杠命令 —— 控制工具本身

  • /chat save|resume|list —— 保存和恢复对话
  • /compress —— 压缩上下文，Token 太多时用
  • /memory add|show|refresh —— 管理持久化背景知识
  • /restore —— 如果 AI 改了你的文件，用这个回滚
  • /stats —— 看 Token 使用量
  • /quit —— 退出

我常用 /chat save 切换不同探索分支，比如同时测试两种代码重构方案。

@ 符号命令 —— 文件注入

这是开发者最常用的功能：

@src/main.go "这段代码有什么问题？"

特性：

  • Git 感知：自动忽略 .gitignore 的内容
  • 支持目录：可以直接传整个文件夹

我踩过的坑：用 @. 注入整个项目根目录，结果包含二进制文件导致解析失败。后来学会指定具体子目录。

! 感叹号命令 —— Shell 直通

!git status
!ls -la

单独输入 ! 可以在 Gemini 模式和纯 Shell 模式间切换。

GitHub/GitLab 工作流

实战：把 Gemini 塞进 GitLab MR 流程

装好工具只是开始，真正的价值要在工作流里体现。

我们团队的做法是：MR 创建时自动触发 Gemini 代码评审，结果推送到飞书。

架构思路

GitLab MR 创建 → Webhook → 中间服务 → 调用 Gemini API → 推送飞书

核心逻辑是：

  1. GitLab Webhook 触发时，通过 API 获取 MR 的 diff
  2. 把 diff 塞进 Prompt，调用 Gemini 分析
  3. 格式化结果，通过 Webhook 推到飞书

Prompt 怎么写

这是关键。我们的 Prompt 长这样：

As an expert Senior Software Engineer, review the following code changes.


Focus on:
1. Potential Bugs & Logical Errors
2. Performance Issues
3. Code Style & Best Practices
4. Maintainability & Readability
5. Security (Basic)


Provide concise, actionable feedback in Markdown.


Code Diff:
```diff
{diff_content}
Gemini 的输出质量比我想象的好，尤其是找出明显的逻辑错误和风格问题。


### 效果如何


![代码评审协作](../../assets/blog/gemini-cli-review.jpg)


跑了一个月的统计：
- 平均 CR 时长缩短约 20-30%
- 常见模式化错误检出率很高
- 开发者反馈说「AI 的建议很直接，不像人类评审那么委婉」


当然也有局限：Gemini 不理解业务上下文，有时候会提出不切实际的建议。我们把它定位为「预审」，最终结果还是要人工把关。


---


## 但我现在不怎么用了


写到这里，我必须诚实地说：我已经迁移到 Antigravity 了。


不是 Gemini CLI 不好，而是生态问题。Antigravity 能反代多个模型（Claude、Codex、Gemini 都支持），不用为每个 API 单独配置一套环境。


Gemini CLI 的双层命令设计确实精巧，但灵活性上输了。我观察到周围不少开发者都在往 Antigravity 或其他多模型 CLI 迁移。


**如果你只是想快速上手一个 AI CLI**，可能直接用 Antigravity 更省事。


**如果你想深入理解这类工具的设计思路**，Gemini CLI 的架构还是值得研究的。它让我明白了「Shell 命令」和「交互式指令」应该如何分工。


---


## 给新手的建议


1. **安装时耐心等 API 启用**，不要重复登录 gcloud
2. **管道传大文件前先截断**，避免 Token 超限
3. **用 `@` 注入文件时指定具体路径**，别用 `@.` 传整个项目
4. **重要操作前先 `/chat save`**，特别是让 AI 改本地文件时
5. **考虑清楚是否需要长期投入**，现在多模型 CLI 可能是更好的选择


---


## 写在最后


配置 Gemini CLI 的那三个小时，让我对 Google 的开发工具体验有了新认识。它们往往设计精巧，但文档和生态跟不上。


写完这篇，我发现自己对 Gemini CLI 的感情很复杂：既欣赏它的架构设计，又对它的前景悲观。这可能就是我上面说的偏见在作祟。


**你还在用 Gemini CLI 吗？** 还是已经迁移到其他工具了？