Gemini CLI使用教程（2026）：安装、认证、GEMINI.md与安全执行

Gemini CLI使用教程2026安装、认证、GEMINI.md与安全执行Gemini CLI怎么用不能只看一条安装命令。一个可复现、可审查的使用流程应覆盖下面六个环节本机环境是否满足要求如何安装稳定版选择哪种官方认证方式怎样让CLI读懂当前项目如何审查文件修改和Shell命令出现登录、版本、权限和额度问题时怎么排查。本文依据Gemini CLI官方文档和截至2026年7月28日的稳定版资料整理。示例使用官方包名、官方认证方式和测试仓库重点说明安装、项目上下文、权限确认与版本控制一、Gemini CLI是什么Gemini CLI是Google维护的开源命令行AI代理。它可以在终端里读取项目文件、解释代码、生成或修改文件、运行测试并把项目说明作为长期上下文加载。它和普通网页版聊天的主要区别是对比项网页版聊天Gemini CLI使用位置浏览器PowerShell、Bash、Zsh等终端项目上下文需要手动上传或粘贴可以读取受信任目录内的文件文件修改以回答内容为主可以提出并执行文件操作命令执行通常不能直接操作本机终端获得批准后可以运行Shell命令项目规则每次对话说明可通过GEMINI.md持续提供需要注意Gemini CLI能操作文件和命令不代表应该给它无限权限。正确做法是从测试仓库开始查看每次变更运行测试后再提交代码。二、2026年最新版本与环境要求截至2026年7月28日官方文档显示最新稳定版为v0.52.0发布日期为2026年7月22日。稳定版适合日常使用preview和nightly包含更新功能但可能存在回归问题不适合没有测试环境的生产项目。官方推荐环境包括Node.js 20.0.0或更高版本Windows 11 24H2、macOS 15或Ubuntu 20.04PowerShell、Bash或Zsh互联网连接普通短会话建议至少4 GB内存大型代码仓库和长会话建议16 GB以上。先检查Node.js与npmnode--version npm--version如果node --version低于20应先从Node.js官方渠道升级。不要为了安装CLI随意下载第三方打包运行库。三、Gemini CLI安装方法1. npm全局安装官方推荐的标准安装命令是npm install-g google/gemini-cli安装完成后检查版本gemini--version启动交互界面gemini2. 不全局安装使用npx临时运行如果只是体验或者不希望向全局npm目录写入包可以使用npx google/gemini-clinpx每次会解析并运行包启动时间可能比全局安装稍长。3. 更新稳定版npm install-g google/gemini-clilatest不建议仅为了追求新功能就直接使用nightly。如果确实需要测试预览版应放在独立环境中npm install-g google/gemini-clipreview四、Gemini CLI登录与认证首次运行geminiCLI会提示选择认证方式。个人开发者在本地交互使用时通常优先选择Sign in with Google随后在浏览器完成Google账号登录。官方支持的主要认证方式包括场景推荐方式是否通常需要Cloud项目个人本地开发Google账号登录通常不需要企业、学校或Workspace账号Google账号登录可能需要AI Studio开发者Gemini API Key不需要Vertex AI项目ADC、服务账号或Cloud API Key需要CI/CD、无浏览器服务器API Key或Vertex AI视方式而定使用API Key认证不要把真实Key写进文章、Git仓库或截图。PowerShell当前会话可以这样设置$env:GEMINI_API_KEYYOUR_GEMINI_API_KEYgeminimacOS或LinuxexportGEMINI_API_KEYYOUR_GEMINI_API_KEYgemini随后在认证选项中选择使用Gemini API Key。安全提醒OAuth凭证只应用于对应的官方认证流程不应提供给其他程序或写入项目文件。自动化或服务端场景应使用官方支持的AI Studio API Key或Vertex AI认证。五、第一次在项目中使用Gemini CLI建议新建一个测试项目而不是直接进入保存生产密钥的仓库。mkdir gemini-cli-demoSet-Locationgemini-cli-demo git init gemini进入后可以先输入低风险、只读型任务请先只读取当前目录不要修改文件。 告诉我项目包含哪些文件并说明每个文件可能承担的职责。再尝试生成计划请为这个项目设计一个最小的Python命令行示例。 先输出实施计划和文件清单等我确认后再修改文件。完成修改后不要直接相信文字总结。退出CLI或在另一终端检查git status gitdiff如果项目有测试python-m pytest这套流程的关键是先解释、再计划、后修改、最后看Diff和测试结果。六、Gemini CLI常用命令启动和非交互查询# 进入交互式REPLgemini# 发送一次性问题gemini-p请概括README.md的核心内容# 查看版本gemini--version# 查看帮助gemini--help交互界面中的常见斜杠命令命令用途/help查看当前版本支持的命令/about查看版本和运行信息/model查看或调整模型选择/stats查看会话与额度相关统计/memory show查看当前加载的项目上下文/memory reload重新加载GEMINI.md/settings查看或修改设置/clear清理终端显示内容/quit退出CLI命令会随版本更新。文章中的列表只用于快速入门实际以当前版本的/help输出为准。文件引用在交互式CLI中可以把文件或目录加入当前问题README.md 请检查安装说明是否缺少前置条件。src/ 请梳理模块依赖只做分析不修改文件。!Shell模式!前缀可以执行Shell命令!git statusShell命令具有与当前终端用户相同的权限。删除、覆盖、安装依赖和执行未知脚本前必须人工确认。七、用GEMINI.md固定项目规范在仓库根目录创建GEMINI.md可以减少重复说明# 项目约定 - Python版本3.12 - 新代码必须包含类型注解 - 修改前先说明原因和影响文件 - 不修改 .env、密钥文件和生产配置 - 完成后运行 python -m pytest - 不通过删除测试来让测试套件通过然后在CLI中检查实际加载内容/memory show修改GEMINI.md后重新加载/memory reload项目级规则应简短、可验证不要写互相冲突的要求。涉及私密信息的个人笔记不应提交到公开仓库。八、常见问题排查1.gemini不是可识别的命令先确认包是否安装npm list-g google/gemini-clinpm config get prefix关闭并重新打开终端让PATH重新加载。如果仍找不到检查npm全局可执行目录是否在PATH中。2. Node.js版本不符合要求node--version需要Node.js 20或更高版本。升级后重新安装CLI。3. 浏览器登录完成但终端仍未认证检查浏览器登录的账号是否与CLI选择一致终端是否被代理、防火墙或企业策略阻断企业或学校账号是否需要Google Cloud项目是否混用了旧的API Key、Google账号和Vertex AI变量。如要切换认证方式应先按官方认证文档清理冲突的环境变量。4. CLI想修改太多文件把任务拆小并明确只允许修改 src/parser.py 和 tests/test_parser.py。 修改前先列出计划不安装依赖不执行网络命令。同时使用git diff检查。不要在未提交的重要工作区里尝试大范围自动修改。5. 达到额度或响应变慢先用/stats查看当前版本提供的统计减少一次性加载的目录缩短无关上下文。额度、模型和认证方式相关不能把某个账号的次数当作所有用户的固定数值。九、CSDN发布与安全检查发布技术教程前建议检查安装包名是否为google/gemini-cli版本日期是否写明示例中没有真实API Key、Cookie、账号或项目ID认证示例只展示占位符不展示或转交真实凭证对版本、额度和执行结果使用可核验的客观表述命令旁边说明影响范围和风险图片与对应段落强相关代码块可以复制路径与系统差异已经说明。十、一个完整的代码仓库实战流程下面以“给现有Python项目增加输入校验”为例演示怎样把任务拆成可审查步骤。第一轮只做仓库理解请只读取当前项目不修改文件。 找出命令行输入的入口、现有校验逻辑和相关测试。 输出调用链、涉及文件和潜在风险。第二轮要求计划但仍不修改目标当用户输入空字符串时返回明确错误。 请给出最小修改计划限制在两个源文件和一个测试文件内。 不要引入新依赖不改变已有公开函数签名。确认计划后再授权修改按刚才的计划修改。每完成一个文件说明修改点。 不要运行删除、覆盖目录或网络下载命令。 修改后运行现有测试并报告失败用例不要为了通过测试而删除断言。随后在外部终端进行独立检查gitdiff--check gitdiffpython-m pytest如果Diff超出约定范围应先回滚或要求重新生成最小补丁而不是继续叠加修改。AI生成的测试也需要人工查看它是否真的覆盖边界条件还是只验证了实现本身。如何让代码审查结果更有用不要只输入“帮我Review代码”。可以指定审查维度请审查这次未提交的变更只报告可以由代码直接证明的问题。 按正确性、安全性、兼容性、性能和可维护性分类。 每个问题写明文件、位置、触发条件和最小修复建议。 如果没有发现高风险问题明确说明不要为了凑数量制造问题。这能减少泛泛而谈的“建议加注释”“建议优化性能”。对于安全问题还应使用静态扫描、依赖审计和人工评审交叉验证不能把CLI回答当作唯一结论。大仓库如何减少无关上下文大型仓库不要一次加载全部目录。可以用.geminiignore排除构建产物、依赖目录、日志和大文件使用src/module/只引用当前模块把项目约定写入短小的GEMINI.md每完成一个独立任务就新建会话并提供最新状态摘要不把.env、证书、数据库备份和用户数据放进可读取范围。减少上下文不仅节省额度也能降低旧代码和无关文件干扰判断的概率。最后建议为每次AI辅助修改保留独立Git提交提交信息写清任务范围、测试结果和人工复核人。这样出现回归时可以快速定位与撤销也便于团队审计自动生成的代码。十一、总结Gemini CLI怎么用可靠的入门顺序是使用Node.js 20安装官方稳定包选择适合自己的官方认证方式在测试仓库内从只读任务开始用GEMINI.md保存项目规则每次修改后检查git diff并运行测试。Gemini CLI是能操作文件和终端的开发工具不是普通聊天窗口。权限越大越要保留人工确认、版本控制和测试。