版权归作者所有，如有转发，请注明文章出处：https://cyrus-studio.github.io/blog/

一、Gemini CLI 是什么

Gemini CLI 是 Google 官方推出的命令行 AI 助手。

它可以：

  • 阅读整个工程

  • 分析代码

  • 修改代码

  • 生成代码

  • 解释报错

  • 帮助重构

  • 编写文档

  • 与 Git 配合工作

  • …

例如：

gemini

进入交互模式：

> 解释 native_bridge.cpp

或者：

> 帮我找 JNI 注册函数

甚至：

> 帮我分析整个 Android 工程

二、安装 Node.js

Gemini CLI 基于 Node.js。

官方下载：https://nodejs.org/

安装完成后打开 PowerShell：

node -v

例如：

v24.18.0

再检查 npm：

npm -v

例如：

11.16.0

说明环境正常。

三、安装 Gemini CLI

打开 PowerShell：

npm install -g @google/gemini-cli

等待安装。

检查：

gemini --version

例如：

0.50.0

说明安装成功。

四、第一次运行

输入：

gemini

word/media/image1.png

第一次会提示：

Sign in with Google

浏览器自动打开：

Google 登录

选择自己的 Google 账号。

授权完成后返回 PowerShell。

word/media/image2.png 即可进入：

>

这就是 Gemini CLI。

五、使用 API Key

除了 Google 登录，还可以使用 Gemini API Key。

获取 API 密钥：https://aistudio.google.com/

复制 API Key 密钥

word/media/image3.png

粘贴 API Key 到 Gemini CLI

word/media/image4.png 以后 Gemini CLI 会自动使用 API。

如何想修改 API Key，可以执行下面的命令：

/auth

终端会弹出一个交互菜单，列出几种身份验证方法。通过方向键选择 “ Use Gemini API Key” 设置新的 API Key。

word/media/image5.png

六、退出 Gemini CLI

按两次快捷键退出：

Ctrl + C

输入退出命令退出：

/exit

或者：

/quit

六、升级 Gemini CLI

升级：

npm update -g @google/gemini-cli

或者：

npm install -g @google/gemini-cli@latest

查看版本：

gemini --version

七、卸载

npm uninstall -g @google/gemini-cli

八、进入工程目录

例如：

D:\Projects\TestApp

PowerShell：

cd D:\Projects\TestApp

然后：

gemini

Trust folder

word/media/image6.png

Gemini 就能看到工程中的所有文件，可以直接分析整个工程。

word/media/image7.png

九、设置代理

执行下面命令设置代理，比如代理软件端口是 16888：

setx HTTPS_PROXY "http://127.0.0.1:16888"
setx HTTP_PROXY "http://127.0.0.1:16888"

查看当前代理

echo $env:HTTPS_PROXY
echo $env:HTTP_PROXY

移除代理

[Environment]::SetEnvironmentVariable("HTTPS_PROXY", $null, "User")
[Environment]::SetEnvironmentVariable("HTTP_PROXY", $null, "User")

注意：当前 PowerShell 不会自动刷新，所以设置或者删除代理后需要：

  1. 关闭 PowerShell

  2. 重新打开

十、.geminiignore

.geminiignore 文件的作用类似于 .gitignore，它专门用于向 Gemini CLI 指示在扫描、搜索和读取代码库时需要忽略/排除哪些文件或目录。

它的主要作用包括：

  1. 提高 Token 效率：避免 AI 在读取文件树、检索代码时，扫描无关的大型文件夹（如依赖包、编译产物、本地缓存等），从而大幅节省 Token 消耗并加快响应速度。

  2. 保护隐私与安全：可以配置忽略包含敏感数据、API 密钥、个人凭证或私密配置的文件，防止这些内容被意外读入 AI 的上下文。

  3. 减少搜索噪点：在进行全局代码搜索时，自动过滤掉二进制文件、第三方库、日志文件等，确保 AI 能够专注于您自己的核心源代码。

比如，可以在工程根目录新建一个 .geminiignore，添加如下内容：

# Git
.git/

# Python
__pycache__/
*.pyc
.venv/

# Build
build/
dist/

# Android
.gradle/
.idea/
*.apk
*.aab
*.dex

# Native build
cmake-build-*/
obj/
libs/

十一、GEMINI.md

GEMINI.md 是在使用 Google Gemini 相关的开发者工具（如 Gemini CLI 或 IDE 插件）时，用来给 AI 提供局部上下文、特定规则和作业指示 的上下文配置文件。

它的核心逻辑类似于项目开发中的 README.md，但 README.md 是写给人类开发者看的，而 GEMINI.md 是写给 Gemini 看的指令书。

Android 工程 GEMINI.md 示例

# Gemini Context & Rules for Android Project

你当前正在作为高级 Android 架构师，协助开发一个现代化的 Android 应用。请在所有的代码生成、重构和审查中严格遵守以下团队规范。

## 1. 核心技术栈与版本约束
- **编程语言**: 100% Kotlin。禁用 Java，除非是遗留类迁移。
- **UI 框架**: Jetpack Compose。严禁使用传统 XML Layouts / ViewBinding。
- **异步处理**: Kotlin Coroutines & Flow。全面替代 RxJava 或 Handler。
- **依赖注入**: Hilt (Dagger-Hilt)。
- **网络层**: Retrofit2 + Serialization (禁用 Gson)。

## 2. 架构模式 (Architecture Style)
项目严格采用基于 Jetpack 组件的 **MVVM (Model-View-ViewModel)** 架构，结合单向数据流 (UDF) 模式：
- **View (Compose)**: 必须是无状态的 (Stateless)。所有的点击事件和 UI 状态必须通过 Lambda 向上抛给 ViewModel，禁止在 Composable 中直接修改状态。
- **ViewModel**: 使用 `MutableStateFlow` 管理 UI 状态，并暴露为只读的 `StateFlow` 给 UI 监听。必须通过 `viewModelScope` 启动协程。
- **Repository**: 作为单一数据源 (SSOT)，负责封装网络请求和本地数据库 (Room)，严禁在 ViewModel 中直接进行网络请求。

## 3. 代码编写与命名规范
- **Compose 命名**: 所有 `@Composable` 函数必须使用 **大驼峰命名法 (PascalCase)** (例如: `HomeScreen`, `OrderListItem`)。
- **状态管理**: 统一使用 `uiState` 命名 ViewModel 的状态流：
  ```kotlin
  private val _uiState = MutableStateFlow<UserUiState>(UserUiState.Loading)
  val uiState: StateFlow<UserUiState> = _uiState.asStateFlow()

你可以将它放置在 Android 项目的根目录 下。当你通过 Gemini 聊天、生成代码或重构时，AI 就会自动遵循这里定义的架构、命名规范和第三方库选择，从而避免写出过时的代码。

补充：与 AGENTS.md 的关系

在 Google 的一些特定生态（如 Android Studio 中的 Gemini 助手）中，你会看到一个非常类似的文件叫 AGENTS.md。它们的作用几乎完全相同，如果同一个目录下同时存在这两个文件，通常云端工具或 IDE 会优先读取 GEMINI.md 。

十二、user location is not supported for the API use

当请求提示如下：

✕ [API Error: {"error":{"message":"{\n  \"error\": {\n    \"code\": 400,\n    \"message\": \"User location is not supported for the
  API use.\",\n    \"status\": \"FAILED_PRECONDITION\"\n  }\n}\n","code":400,"status":"Bad Request"}}]

也就是说，API 服务根据你的请求来源判断你的地理位置（通常通过 IP、账号地区等），发现该地区不在支持列表中，因此拒绝请求。

首先确认自己的 IP 地址是否在可用地区，比如可以在 https://gemini.google.com/app 设置中看到当前自己的 IP 地址所在的地区

word/media/image8.png

或者 google 搜索 where am i

word/media/image9.png

如果不是就切换到支持的节点再刷新一下看看。

再看看自己的账号关联地址，点击账号头像，点击右下角的服务条款。

word/media/image10.png

可以看到账号的关联地区

word/media/image11.png

另外如何你的账号还没做年龄认证也会拒绝请求，点击下面链接扫脸认证一下就行了。

https://myaccount.google.com/age-verification/selfie/privateid/init?hl=en&utm_source=p0

十三、会话管理

进入 Gemini：

gemini

打开会话列表：

/resume

上下选择会话，Enter 进入会话，x 删除会话，q 退出

word/media/image12.png

恢复最近一次会话

gemini -r

或者：

gemini --resume

命令行查看会话列表

gemini --list-sessions

例如：

1 Android Hook
2 OpenSSL
3 Test

删除第2个会话：

gemini --delete-session 2

Session 存储位置：

C:\Users\<用户名>\.gemini\tmp\

十四、切换 Gemini 模型

Gemini CLI 支持：

  • Auto 自动选择

  • Pro 高质量推理

  • Flash 高速度

方法 1：启动时指定模型

例如：

gemini --model gemini-3.1-flash-lite

或者：

gemini -m gemini-3.1-flash-lite

方法 2：配置文件

编辑：

~/.gemini/settings.json

例如：

{
  "model": {
    "name": "gemini-2.5-pro"
  }
}

方法 3：会话中动态切换模型

进入 Gemini：

gemini

输入：

/model

出现选择：

word/media/image13.png 选择对应的模型，之后的新请求使用新指定的模型。

十五、Google AI 模型选型

彻底免费的开源模型（可本地下载或在平台免费跑）

  • gemma-4-31b-it

  • gemma-4-26b-a4b-it

这两款是 Google 发布的 Gemma 4 开源大模型。由于采用了 Apache 2.0 开源协议，它们的模型权重是完全公开且免费的。你可以通过 Ollama 或 Hugging Face 免费下载到自己的本地电脑/服务器上运行，或者在 Kaggle、Hugging Face Spaces 等平台上免费在线试用。

以下模型在免费层级（Free Tier）下是可以免费调用的（有每分钟/每日请求次数限制，通常不可用于高并发商用）：

  • gemini-3.1-flash-lite（在 AI Studio 中提供免费 API 额度，非常适合轻量、快速的对话）

  • gemini-3-flash-preview / gemini-3.5-flash（Flash 系列在测试和预览阶段通常都有非常宽裕的免费测试额度）

  • gemini-3.1-pro-preview / gemini-2.5-pro（Pro 系列的预览版一般也提供免费限额，但正式商用后 Pro 级别通常需要付费）

如果你只是日常对话、写代码或测试，选 gemini-3.1-flash-lite 或者切换到 gemini-3.5-flash 即可，它们在云端端调用最省心且有免费额度；