用 Codex 写公司 ERP 前端的时候感觉还凑合,结合 DESIGN.md 定好设计风格之后也算顺手。但轮到自己的项目,审美这块就开始拉胯了,生成出来的页面怎么看怎么像2015年的产物。后来试了 Gemini CLI,配合 Google Stitch 做原型,感觉确实不一样,有那么点设计感了。趁着这段时间用得比较多,把 Gemini CLI 的核心用法整理出来,希望对你有用。 Gemini CLI 是什么
简单说,它是 Google 开源的 AI Agent,把 Gemini 模型能力直接塞进了终端。它不是那种你问一句它答一句的简单聊天工具,而是一个有 ReAct(推理-行动)循环的智能代理,能读取和修改本地文件与代码库、执行 Shell 命令(带权限控制)、调用 Google Search 联网搜索、抓取网页内容,还能通过 MCP 协议接入外部工具,以及处理图片、PDF、音频、视频等多模态输入。
核心优势有几点值得单独说:个人 Google 账号每天 1000 次请求、每分钟 60 次,完全免费;跑的是 Gemini 3 系列(目前最新已到 Gemini 3.1 Pro Preview),支持 100 万 Token 上下文窗口;Google Search、文件操作、Shell 命令、网页抓取全都内置;Google Cloud Shell 里预装好了,不用额外折腾。
安装与环境配置
Node.js 18 以上版本,推荐 20+,macOS、Linux、Windows(含 WSL)都支持,能访问 Google 服务就行。
验证 Node.js 版本:
安装方式有几种,最推荐的是 npm 全局安装:
不想全局装也可以直接用 npx:
数据科学场景用 Conda 的话:
想尝鲜可以装预览版(功能最新,但可能不稳定):
升级、卸载也就一条命令的事:
配置文件分两层——用户全局在 ~/.gemini/settings.json,项目级在 .gemini/settings.json,项目设置会覆盖用户设置。
认证方式选哪个
个人用的话直接 Google 账号 OAuth 最省事,首次运行 gemini 会自动引导你登录。
⚠️ 有个坑要提前说: 如果系统里设置了 GOOGLE_API_KEY、GEMINI_API_KEY 或 GOOGLE_GENAI_USE_VERTEXAI 环境变量,CLI 会优先走付费 API 通道,就算你选了 Google 账号登录也没用。只想用免费 OAuth 的话,确认这几个变量没被设置。
常用命令行参数
几个最常用的参数得记住:
-p 非交互模式直接执行:gemini -p "分析这个文件"
-m 指定模型:gemini -m gemini-3.1-flash-lite-preview
--approval-mode plan 只规划不执行(重构前先看计划很有用)
--checkpointing 每次工具调用前自动保存快照(重要任务强烈推荐)
当前主要模型选择:
gemini-3.1-pro-preview:最强推理,100万Token上下文,适合复杂分析和架构设计
gemini-3.1-flash-lite-preview:快速高效,成本低,日常任务和快速迭代首选
会话内斜杠命令速查
进入交互模式后,输入 / 就能看到命令列表,常用的有这些:
会话管理:
/chat save 文件名 导出会话为 Markdown 或 JSON
/compress 用摘要替换完整历史,节省 Token
/restore 列出检查点,/restore 恢复到指定快照
配置与信息:
/status 查看会话状态(模型、认证、配额等)
工具与扩展:
内存与上下文:
/memory show 显示合并后的完整上下文内容
/memory add 文本 向当前会话内存添加文本
/memory refresh 从磁盘重新加载 GEMINI.md
@ 文件引用和 ! Shell 命令
在提示词里用 @路径 把文件或目录内容注入上下文:
文本、代码、图片(PNG/JPG/WebP/GIF)、PDF、音频、视频都支持,引用目录时会自动跳过 .gitignore 里的内容。
用 ! 前缀直接执行 Shell 命令:
单独输入 ! 还能进入持久 Shell 模式,再输入一次 ! 退出。
GEMINI.md 项目上下文文件
这个东西类似给 AI 的"项目说明书",放在项目根目录,每次启动会自动加载。内容建议包含:项目技术栈、关键命令(dev/test/build)、代码规范、文件组织方式、禁止操作等。多层级的 GEMINI.md 会被合并,越深的目录优先级越高。
用 /init 命令让 AI 自动分析当前项目结构来生成一份:
类似 .gitignore 的 .geminiignore 文件可以排除不该被读取的文件,node_modules/、.env、*.secret 这类都应该加进去。
几个真实工作流
陌生代码库快速上手:
新功能开发(带检查点):
Bug 修复:
CI/CD 自动化:
MCP 集成
在 settings.json 里配置好 MCP Server,就能直接在提示词里调用外部工具:
配好之后这样用:
如果 MCP Server 定义了 Prompts,它们会自动变成斜杠命令可以直接调用。
几个必须注意的安全坑
API Key 永远不要硬编码在代码里,不要提交含 Key 的 .env 文件,.geminiignore 里排除所有包含凭证的文件;--yolo 模式会跳过所有确认,生产机器上禁止使用;大范围文件修改前一定开 --checkpointing,等同于自动 git stash;长会话记得用 /compress 压缩历史节省 Token;企业用户如果有数据保密要求,走 Vertex AI 并启用数据保护协议。
Gemini CLI 的上手门槛其实不高,一个 Google 账号加几条命令就能跑起来。它真正的价值在于把 AI 能力嵌进你原有的终端工作流——不是另开一个浏览器标签去对话,而是在代码库旁边直接分析、修改、执行。用熟之后,很多以前要反复切换窗口的工作都能在一个终端里搞定,这才是它和那些网页版 AI 工具最本质的区别。