Gemini CLI 安装与配置：Windows/macOS/Linux 环境搭建及 API Key 设置

初次部署 Gemini CLI 时，阻碍进度的往往不是 AI 功能本身，而是终端中 node 或 npm 报出“命令未找到”的错误；也有用户在安装完成后，困惑于该选择 Google 账号登录还是配置 API Key。只要确保当前终端能正确识别 Node.js 和 npm，按顺序完成 CLI 安装并根据账号类型进行认证，整个流程即可顺利推进。

先确认 Node.js 和 npm 能正常运行

根据官方文档，通过 npm 安装 Gemini CLI 需要 Node.js 20.0.0 或更高版本作为运行时支持。请在常用终端中分别执行 node --version 和 npm --version。若两条命令均返回版本号，表明环境已就绪；若提示“无法识别命令”，则需先安装 Node.js，随后关闭并重启终端以刷新环境变量。

Windows 用户可使用 PowerShell，macOS 用户打开“终端”，Linux 用户则使用发行版自带的终端程序。无需急于修改系统路径或尝试复杂的安装方案，通常只需重新开启一个终端窗口，新安装的命令即可生效。

先确认运行环境，再通过 npm 安装 Gemini CLI。

用 npm 安装并启动 Gemini CLI

在终端中运行以下官方提供的全局安装命令：

npm install -g @google/gemini-cli

安装完成后，输入 gemini 即可启动。Windows、macOS 和 Linux 均可遵循此 npm 安装路径；若安装过程提示权限不足，请仔细甄别报错来源，切勿盲目复制不明命令。此外，也可使用 npx @google/gemini-cli 进行临时启动，这种方式适合希望快速体验且不愿进行全局安装的用户。

若系统提示找不到 gemini，首先确认安装命令是否已成功执行，然后重启终端再次尝试。若问题依旧，请检查 npm 的全局可执行目录是否已添加至系统的 PATH 环境变量中，避免直接套用其他操作系统的配置方法。

首次启动时选择合适的认证方式

启动后将进入认证方式选择界面。个人用户通常可选择“Sign in with Google”，并按指引在浏览器中完成登录，CLI 会自动缓存后续所需的凭据。对于学校、企业或 Google Workspace 账号用户，可能还需按照组织管理员的要求配置 Google Cloud 项目。

个人用户可从 Google 账号登录开始。

若使用 Google AI Studio 提供的 Gemini API Key，请选择 API Key 认证方式。请先在 AI Studio 获取密钥，并将其设置为环境变量，严禁将密钥粘贴至公开文章、截图或代码仓库中。在 Windows PowerShell 当前会话中，可执行以下命令：

$env:GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

在 macOS 或 Linux 的 Bash、Zsh 终端中，可执行以下命令：

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

将占位符替换为实际密钥后，运行 gemini 并选择“Use Gemini API key”。需注意，上述 PowerShell 设置仅对当前窗口有效；若需永久生效，应根据各自系统的环境变量配置方法进行保存，同时务必防止密钥泄露至共享配置或日志文件中。

按当前终端类型设置 API Key 环境变量。

遭遇认证问题时，应先区分是 CLI 安装失败，还是账号、项目或密钥配置不匹配：个人用户优先尝试 Google 登录；组织用户需核对 Cloud 项目要求；API Key 用户则需确认变量名与当前终端环境一致。按此三步逐项排查，比反复重装更能精准定位问题。