Gemini 使用指南

Appearance

Gemini CLI 安装教程：下载、Google 登录与 API Key 配置 ​

更新日期：2026年10月09日。安装与调用示例依据 Google Gemini CLI 官方仓库 README 核对；版本要求、权限和额度以当前官方文档为准。

Gemini CLI 是 Google 开源的终端 AI 智能体，CLI 即 Command Line Interface（命令行界面）。它可以结合文件读取、代码编辑和 Shell 工具处理开发任务，适合在项目目录里理解代码、分析报错和辅助修改。本文介绍安装、Google 账号登录与 Gemini API Key 配置，让你先跑通一个小任务，再逐步增加权限。

一、Gemini CLI 和 Gemini 官网、API 有什么区别？ ​

方式主要用途运行位置
Gemini 官网日常聊天、写作与文件问答浏览器或手机应用
Gemini CLI结合本地项目与工具完成开发任务终端
Gemini API将模型能力集成到自己开发的程序应用后端或脚本

CLI 是一个工具入口，API 是开发接口，两者并非同一种产品。CLI 可以通过 Google 登录，也可以使用 API Key；选哪种认证会影响账号权限、计费和配额归属。若只想聊天，可先阅读 Gemini 官网与下载指南，不必为此配置开发环境。

二、Gemini CLI 安装：npm、npx 与 Homebrew 三种方式 ​

官方源码位于 google-gemini/gemini-cli，npm 包名为 @google/gemini-cli。安装前核对完整包名，避免将名称相近的第三方工具当作官方版本。

先确认运行环境 ​

使用 npm 或 npx 方案时，先安装满足 官方安装文档 要求的 Node.js，再检查终端能否识别命令：

bash
node --version
npm --version

Node.js 的版本要求会随 CLI 更新，旧文章中的固定版本号可能不再适用。Windows 用户还应按文档核对当前支持的终端环境；在 Windows 与 WSL 之间切换时，两边安装路径和配置并不自动共享。

临时体验：npx ​

bash
npx @google/gemini-cli

这适合先试用一次。npx 可能下载并缓存软件包，首次启动需要网络连接；“不需要全局安装”并不代表离线运行，也不代表模型在本地执行。

长期使用：npm 全局安装 ​

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

latest 对应官方稳定发布通道。初次使用建议先选稳定版；升级时可再次运行相同安装命令。不要在 npm 权限报错后直接赋予整个系统目录过宽权限，应检查 Node.js 的安装方式和 npm 全局目录。

macOS / Linux：Homebrew ​

已经使用 Homebrew 管理软件的用户，也可按官方 README 安装：

bash
brew install gemini-cli
gemini

三种方式选择一种即可。如果系统里装了多个版本，优先确认当前终端实际调用的安装位置，避免更新了一个副本却仍启动另一个。

三、Gemini CLI 登录：Google 账号还是 Gemini API Key？ ​

方式一：Google 账号登录 ​

启动 gemini 后，选择 Sign in with Google，按浏览器提示完成授权。这种方式适合个人开发者，通常无需手动管理 API Key。组织账号、Code Assist 授权或相关项目要求，应查看 官方认证说明。

授权前核对页面来源和申请权限。若浏览器显示登录成功而终端没有继续，应确认回调过程是否完成，以及浏览器与 CLI 是否运行在同一个环境中。

方式二：Gemini API Key ​

在 Google AI Studio API Key 页面 创建或选择密钥，核对所属项目及计费状态。将密钥通过环境变量传给 CLI，再选择 Gemini API Key 认证方式。

macOS / Linux 的 Bash 可使用隐藏输入，减少将真实密钥写入命令历史的机会：

bash
read -r -s -p 'Gemini API Key: ' GEMINI_API_KEY
printf '\n'
export GEMINI_API_KEY
gemini

macOS 默认的 zsh 使用不同的提示语法：

zsh
read -r -s 'GEMINI_API_KEY?Gemini API Key: '
printf '\n'
export GEMINI_API_KEY
gemini

Windows PowerShell 7 可使用：

powershell
$env:GEMINI_API_KEY = Read-Host 'Gemini API Key' -MaskInput
gemini

以上变量在当前终端会话中生效；关闭终端后，如未做持久配置，需要重新输入。隐藏输入只能减少屏幕和历史记录泄露，环境变量本身不是密钥保险箱。不要把真实 Key 写进 GEMINI.md、公开仓库、前端代码或报错截图；泄露后应在控制台撤销并更换。

方式三：Vertex AI ​

已有 Google Cloud 项目、企业权限和计费管理的团队，可按官方认证文档配置 Vertex AI。它需要独立检查项目、身份和权限，不能仅凭已有 Gemini 网页订阅推断可用。

四、Gemini CLI 第一个任务：先分析，再修改 ​

进入需要处理的项目目录，然后启动 CLI：

bash
cd your-project
git status --short
gemini

先了解目录和未提交修改，再给它一个明确、容易核验的任务：

text
请阅读 README 和 package.json，说明这个项目如何启动和测试。
每条说明给出文件路径与依据。不要修改文件，不要执行安装命令。
资料不足时列出需要确认的问题，不要自行猜测。

确认它正确理解项目后，再提供报错、预期行为和验收条件。例如：“定位登录按钮点击后无响应的原因，先解释相关调用链，再给出最小修改和验证步骤。”CLI 提出的工具调用要结合实际权限提示检查，不能只靠提示词当作访问控制。

项目级规则可以写入 GEMINI.md，记录语言版本、测试方式、代码风格和需要排除的敏感目录。它提供上下文指引，不会自动阻止读取文件，也不应包含密码或令牌。更多规则可查看 官方上下文文件说明。

五、Gemini API 额度与 CLI 脚本调用 ​

Google 登录、API Key 和 Vertex AI 有各自的配额及条款；不要把其中一个渠道的免费额度套用到另外两个渠道。API Key 方式尤其要确认项目是否开启计费、所选模型是否收费，以及触发限流后程序如何处理。

官方 CLI 支持 -p 参数进行非交互调用，例如：

bash
gemini -p "用中文解释这个项目的目录结构，引用文件路径，不要修改文件"

需要程序读取结果时，可使用结构化输出：

bash
gemini -p "总结 README 中的启动步骤，不要执行命令" --output-format json

JSON 输出有 CLI 自身的封装结构，不等于任意提示词都会得到符合业务 Schema 的内容。接入自动化前，应核对 官方无界面运行说明，处理退出状态、超时、认证失效和限流。先在测试项目试运行，再加入持续集成，避免重复请求导致费用累积。

六、常见问题 ​

安装后提示 gemini: command not found 怎么办？ ​

先运行 npm list -g --depth=0 确认包是否装在当前 Node.js 环境，再用 npm prefix -g 查看全局安装前缀。检查可执行文件目录是否在 PATH 中，并重新打开终端；不要将安装输出中的错误当作安装成功。

Gemini CLI 可以免费使用吗？ ​

官方提供的免费使用机会受认证方式、账号条件和配额影响。以 官方配额与条款 以及 Gemini API 价格页 为准，不应承诺无限使用。

API Key 无效、403 或 429 应该怎样排查？ ​

密钥无效先检查当前会话是否配置正确以及密钥是否被撤销；403 应阅读完整错误内容，核对权限、服务启用和地区条件；429 则检查速率与配额。不要对权限错误无限重试，也不要通过反复创建账号规避配额。

CLI 能用中文，也能自动修改代码吗？ ​

可以用中文描述任务。CLI 有文件与 Shell 工具，但是否执行取决于配置、权限和确认过程；修改后仍需检查 git diff 并运行项目测试，模型的回答不能代替实际验证。

七、结语与使用说明 ​

安装 Gemini CLI 的关键是认准官方软件包，按需求选择 Google 登录或 Gemini API Key，然后从一个能核对结果的小任务开始。收藏官方安装和认证文档，升级前检查变更记录，能减少版本、权限与计费方面的误判。

本文与 Google 无隶属关系。命令示例用于说明操作流程，不构成对特定账号可用性或费用的保证；使用时遵守当地法律法规及平台条款。CLI 会调用云端服务，处理代码、客户资料和其他敏感文件前，应核对数据政策和项目授权范围。

最后更新于:

Gemini 中文版博客

Copyright © 2025-2026