Gemini-CLI 终极教程 | 从入门到精通

前言：为什么选择 Gemini-CLI？

在众多 AI 工具中，Gemini-CLI 凭借其独特的设计理念和强大的功能集脱颖而出：

                        终端原生: 它直接存在于您最熟悉的开发环境——终端中，无需切换窗口，实现了沉浸式、高效的工作流。
深度上下文感知: 通过 @ 命令、GEMINI.MD 文件以及与 IDE
                                的集成，它能深刻理解您的项目结构、代码库和编码规范。
强大的自主代理能力: 它不仅能聊天，还能通过内置工具集读写文件、执行命令、搜索网络，并利用推理循环（ReAct loop）来完成修复
                                Bug、构建新功能等复杂任务。
IDE 深度集成: 与 VS Code
                                等编辑器无缝协作，能够感知您当前打开的文件和选中的代码，并直接在编辑器中提供代码修改的可视化比对（diffing）。
高度可扩展: 支持通过自定义命令进行功能扩展，您可以根据自己的需求，打造专属的自动化工具。

                    

第一部分：安装与初次启动

1. 环境准备

在安装前，请确保您的系统已安装 Node.js (推荐 v20 或更高版本) 和 npm。您可以在终端运行以下命令来检查：

检查环境

node -v
npm -v

2. 全局安装

打开您的终端，运行以下命令进行全局安装：

安装命令

npm install -g @google/gemini-cli

3. 首次运行与认证

安装成功后，在终端输入 gemini 并按回车。首次运行时，它会引导您完成认证：

选择认证方式: 推荐选择 "Login with Google"。

浏览器授权: 您的浏览器将自动打开一个 Google 登录和授权页面。

完成返回: 完成授权后，返回终端，您就可以开始与 Gemini 对话了。

第二部分：核心交互模式

掌握与 Gemini-CLI 交互的三种基本方式是高效使用的关键：

💬

自然语言提示

这是最基础的交互方式。直接输入您的问题或指令，就像聊天一样。

请帮我用 Python 写一个快速排序算法。

📂

@ 命令：文件/目录上下文注入

使用 @ 符号，可以将本地文件或整个目录的内容作为上下文提供给 Gemini。

请根据 @./src/utils.js 文件中的代码风格，为这个新函数添加注释。

⚡

! 命令：直接执行 Shell 命令

使用 ! 符号，可以直接在 CLI 内部执行任何终端命令，无需退出。

!git status

第三部分：斜杠(/)命令终极解析

斜杠 (/) 命令是控制和管理 Gemini-CLI 的核心。

一、会话与历史管理

`/chat`

管理对话会话的生命周期

/chat save <tag>: 保存当前完整的对话状态
/chat resume <tag>: 恢复一个之前保存的对话
/chat list: 列出所有已保存的会话标签
/chat clear: 清空当前对话的历史记录

`/history`

查看当前对话的详细历史记录

`/compress`

将当前冗长的对话历史压缩成一个简洁的摘要，以节省 Token

`/copy`

将 Gemini 的上一个回答完整地复制到您的系统剪贴板中

`/clear`

清空终端屏幕（视觉操作，不影响会话数据）

二、上下文与记忆管理

`/memory`

管理从 GEMINI.MD 文件中加载的长期记忆

/memory show: 显示当前所有已加载的文件内容
/memory refresh: 重新加载所有记忆文件
/memory add "<text>": 临时向当前会话添加文本指令

`/context`

查看当前完整的上下文

/context show: 显示即将发送给模型的所有信息

`/directory`

管理工作区目录，用于指定和切换 Gemini-CLI 的工作环境

三、工具与集成

`/tools`

列出当前会话所有可用的工具及其状态（启用/禁用）

`/extensions`

列出当前活动的扩展

`/init`

分析当前项目并创建一个量身定制的 GEMINI.MD 文件

`/mcp`

管理与模型上下文协议 (MCP) 服务器的连接

`/ide`

控制与 IDE 的集成功能

/ide enable: 启用集成
/ide disable: 禁用集成

`/setup-github`

帮助您在当前的 Git 仓库中配置 Gemini-CLI 的 GitHub Actions 工作流

`/yolo`

"You Only Look Once" 模式。启用后，工具执行无需手动确认

⚠️ 请谨慎使用

四、配置与信息

`/help` 或 `/?`

显示所有可用的斜杠命令及其简要说明

`/about`

显示 Gemini-CLI 的版本号和相关的官方链接

`/auth`

管理您的身份验证方式

`/settings`

打开全局 settings.json 配置文件或显示其路径

`/stats`

显示当前会话的详细统计数据

`/theme`

更改 CLI 界面的颜色主题

`/docs`

在您的默认浏览器中打开 Gemini-CLI 的官方完整文档页面

`/editor`

设置当 Gemini 需要打开文件时使用的默认命令行编辑器

`/bug`

引导您报告一个 Bug

`/feedback`

提供一个快速的渠道来提交关于 Gemini-CLI 使用体验的反馈

`/log`

显示日志文件的路径或内容

`/privacy`

显示隐私政策声明

五、特殊模式与切换

`/vim`

开启或关闭 Vim 模式，允许在输入时使用 Vim 快捷键

`/corgi`

切换 Corgi 模式，一个有趣的彩蛋功能 🐶

`/restore`

撤销由工具对项目所做的更改（需在启动时使用 --checkpointing 标志）

`/quit` 或 `/exit`

退出 Gemini-CLI 交互式会话

第四部分：高级技巧与工作流

1. 代码调试工作流

使用 @/path/to/file.py 载入问题代码

提问："分析这段代码可能出现的 IndexError 异常，并给出修复建议。"

使用 !pytest tests/ 运行相关测试

让 Gemini 直接生成修复后的代码，并使用 /copy 粘贴

2. 自动化文档生成

在项目根目录创建 GEMINI.MD，写入指令："所有文档需为 Markdown 格式，包含代码示例。"

运行 /memory refresh 加载指令

提问："请为 @./src/ 目录下的所有模块生成 API 文档。"

3. 项目重构工作流

使用 @./src/ 加载整个源码目录

提问："分析代码结构，建议重构方案以提高可维护性"

让 Gemini 生成具体的重构代码，并逐个文件应用修改

使用 !npm test 验证重构后的代码功能正常

4. 性能优化工作流

运行 !npm run build 构建项目并分析输出

使用 @package.json @webpack.config.js 加载配置文件

提问："基于当前配置，建议性能优化策略"

实施建议的优化方案，并使用 !npm run analyze 验证效果

5. 团队协作工作流

使用 /setup-github 配置 GitHub Actions 工作流

创建团队共享的 GEMINI.MD 文件，定义编码规范和项目约定

使用 @CONTRIBUTING.md 生成贡献指南和代码审查清单

定期使用 /stats 监控项目开发进度和代码质量指标

第五部分：深度自定义

1. 配置 settings.json

运行 /settings 找到并打开配置文件。

常用配置项：

settings.json

{
  "model": "gemini-1.5-pro-latest",
  "temperature": 0.8,
  "tools": {
    "shell": {
      "execute": false
    }
  }
}

修改默认模型: "model": "gemini-1.5-pro-latest"
调整创造性: "temperature": 0.8
禁用危险工具: "tools": { "shell": { "execute": false } }

2. 创建自定义斜杠命令

您可以创建自己的自定义命令来扩展 Gemini-CLI 的功能。

找到您的命令目录（通常是 ~/.gemini/commands）

在该目录下创建一个名为 deploy 的可执行脚本文件

deploy 脚本示例

#!/bin/bash
echo "🚀 开始部署项目..."
# 在此添加您的部署命令，例如：
# gcloud app deploy
echo "✅ 部署完成！"

赋予执行权限：chmod +x ~/.gemini/commands/deploy

重启 Gemini-CLI，现在您就可以直接运行 /deploy 了！

3. 高级配置示例

针对不同使用场景的高级配置示例：

开发环境配置：

development-settings.json

{
  "model": "gemini-1.5-pro-latest",
  "temperature": 0.7,
  "maxTokens": 8192,
  "tools": {
    "shell": {
      "execute": true,
      "workingDirectory": "./"
    },
    "filesystem": {
      "read": true,
      "write": true
    }
  },
  "memory": {
    "autoLoad": true,
    "paths": ["GEMINI.MD", "docs/*.md"]
  },
  "ide": {
    "integration": true,
    "editor": "code"
  }
}

生产环境配置：

production-settings.json

{
  "model": "gemini-1.5-pro-latest",
  "temperature": 0.3,
  "maxTokens": 4096,
  "tools": {
    "shell": {
      "execute": false
    },
    "filesystem": {
      "read": true,
      "write": false
    }
  },
  "safety": {
    "confirmBeforeExecution": true,
    "restrictedCommands": ["rm", "del", "format"]
  },
  "logging": {
    "level": "info",
    "auditTrail": true
  }
}

4. GEMINI.MD 最佳实践

创建高质量的 GEMINI.MD 文件来优化 AI 助手的表现：

项目级 GEMINI.MD 示例：

GEMINI.MD

# 项目配置

## 技术栈
- Frontend: React 18 + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL
- Testing: Jest + React Testing Library

## 编码规范
- 使用 TypeScript strict 模式
- 组件命名采用 PascalCase
- 函数命名采用 camelCase
- 所有公共 API 需要注释
- 优先使用函数式组件

## 文件结构
```
src/
├── components/     # 可复用组件
├── pages/          # 页面组件
├── hooks/          # 自定义 Hook
├── utils/          # 工具函数
├── types/          # TypeScript 类型定义
└── tests/          # 测试文件
```

## 开发流程
1. 创建 feature 分支
2. 完成开发并编写测试
3. 运行 `npm test` 确保所有测试通过
4. 提交 PR 等待代码审查

第六部分：常见问题解答 (FAQ)

Q: 安装时出现权限错误怎么办？

A: 尝试修复 npm 的全局包权限，避免直接使用 sudo。可以采取以下方法：

Windows: 以管理员身份运行命令提示符
macOS/Linux: 使用 npm config set prefix ~/.npm-global 设置全局目录
更改所有者: sudo chown -R $(whoami) ~/.npm
使用 nvm: 考虑使用 Node Version Manager 管理 Node.js 版本

Q: Gemini 似乎没有理解我的项目文件？

A: 如果 Gemini 没有理解您的项目文件，请检查以下几点：

检查文件路径: 确认 @./path/to/file 路径正确
使用相对路径: 建议使用 @./src/ 而不是绝对路径
检查上下文: 使用 /context show 查看当前上下文
创建 GEMINI.MD: 在项目根目录创建该文件说明项目结构
重新加载: 使用 /memory refresh 重新加载配置

Q: 如何重置认证信息？

A: 重置认证信息可以通过以下方式：

使用命令: 运行 /auth 命令进入认证管理
手动删除: 删除 ~/.gemini/auth 文件夹
清除缓存: 运行 gemini --clear-auth（如果支持）
重新登录: 重启 Gemini-CLI 并选择新的认证方式
检查权限: 确保 Google 账户有 Gemini API 访问权限

Q: 如何优化 Gemini-CLI 的性能？

A: 可以通过以下方式优化：

降低 temperature 值以获得更一致的结果
设置适当的 maxTokens 限制
使用 /compress 压缩长对话历史
合理组织 GEMINI.MD 文件内容

Q: 可以在没有网络的情况下使用吗？

A: Gemini-CLI 需要网络连接才能与 AI 模型通信。但是部分本地功能（如文件操作、项目管理）仍然可以使用。

Q: 如何处理敏感代码和数据？

A: 建议采取以下措施：

在生产环境中禁用文件写入功能
使用 .gitignore 排除敏感文件
在 GEMINI.MD 中明确数据处理规则
定期审查会话历史和日志

Q: 支持哪些编程语言和框架？

A: Gemini-CLI 支持几乎所有主流编程语言和框架，包括但不限于：

JavaScript/TypeScript（React, Vue, Angular）
Python（Django, Flask, FastAPI）
Java（Spring, Spring Boot）
C#（.NET, ASP.NET）
Go, Rust, PHP 等

Q: 如何处理大型项目和复杂代码库？

A: 对于大型项目，建议采用以下策略：

分模块处理: 使用 @./src/components/ 逐个模块分析
创建多个 GEMINI.MD: 在不同模块目录下创建特定配置
使用指令集: 创建自定义命令简化常用操作
合理使用 Token: 设置 maxTokens 限制避免超出上限
使用缓存: 利用 /chat save 保存上下文

Q: 在 CI/CD 环境中如何使用 Gemini-CLI？

A: 在 CI/CD 中使用 Gemini-CLI 需要注意以下几点：

环境变量: 设置 GEMINI_API_KEY 作为秘密变量
非交互模式: 使用 --non-interactive 标志
禁用危险操作: 在配置中禁用文件写入和 Shell 执行
使用 Docker: 创建包含 Gemini-CLI 的容器镜像
日志记录: 启用详细日志以便调试

Q: 遇到网络连接或 API 限制问题怎么办？

A: 如果遇到网络或 API 问题，可以尝试：

检查网络: 确保网络连接稳定且可访问 Google 服务
重试机制: 使用 --retry 参数启用自动重试
调整超时: 增加 timeout 设置值
检查配额: 登录 Google Cloud Console 检查 API 使用情况
使用代理: 如需要，配置 HTTP 代理设置

结语

您已经完成了 Gemini-CLI 的终极教程。但真正的掌握来自于不断的实践。现在，就把它应用到您的日常工作中，探索它与您的个人工作流相结合的无限可能。祝您编码愉快！

重新开始学习访问 GitHub

Gemini-CLI 终极教程 从入门到精通

终端原生

深度上下文

自主代理

IDE集成

前言：为什么选择 Gemini-CLI？

第一部分：安装与初次启动

1. 环境准备

2. 全局安装

3. 首次运行与认证

第二部分：核心交互模式

自然语言提示

@ 命令：文件/目录上下文注入

! 命令：直接执行 Shell 命令

第三部分：斜杠(/)命令终极解析

一、会话与历史管理

/chat

/history

/compress

/copy

/clear

二、上下文与记忆管理

/memory

/context

/directory