Deepseek ArtifactsDeepseek Artifacts
Gemini CLI 故障排查

Gemini CLI 不能用？安装、认证与启动错误一次修好

Gemini CLI 启动不了、Google 登录被拒、或者报 "'gemini' 不是内部或外部命令"？按顺序处理：修复 Windows PATH、排掉两个真实的 Google 账号登录报错、再决定用 OAuth 还是 API key。

开始跟着做跳到常见问题

太长不看

  • npm 安装成功后提示 "'gemini' 不是内部或外部命令"，是 PATH 问题，不是安装坏了。先跑 npm config get prefix，把它打印的目录（C:\Users\<你>\AppData\Roaming\npm）加进用户 PATH，然后重开终端。
  • 登录时报 "This account requires setting the GOOGLE_CLOUD_PROJECT env var"？个人免费账号、AI Pro 或 AI Ultra 根本不需要设它——只有 Workspace 账号、Code Assist 授权席位、未成年人和不支持地区才要。
  • 报 "Not eligible for Gemini Code Assist for individuals … 18 years old or older" 说明这个 Google 账号没有确认过年龄。去 Google 的年龄状态页完成年龄验证，再运行 gemini 重新登录。
  • 登录连续失败两次还进不去？别纠结 OAuth，去 AI Studio 领一个 Gemini API key，导出为 GEMINI_API_KEY 就行——它有独立免费额度。认证失败的退出码是 41。

How to Fix Gemini CLI is Not Recognized Error in Windows (Step by Step)

频道：Web Tech Knowledge4:38

观看

Several error issues encountered when logging into Gemini CLI with a Google account

频道：AttackOnLife2:56

观看

Troubleshooting — official documentation

官方文档：google-gemini.github.io

观看

Authentication setup — official documentation

官方文档：google-gemini.github.io

观看

本页的每条命令、报错原文和对话框截图都对照过 Gemini CLI 官方认证与故障排查文档。Windows 录屏是安装与 PATH 修复的视觉来源；macOS 录屏贡献了两个真实的 Google 账号登录报错，以及解开它们的年龄验证流程。

截图版权归原作者所有，并深链到对应时间点；未使用任何人脸画面。

一步一步修好 Gemini CLI

第 1 部分 — "'gemini' 不是内部或外部命令"：修复 Windows PATH

  1. 1

    先复现确切的报错

    录屏里 npm install -g @google/gemini-cli 干净地跑完——"changed 577 packages in 4m"——但输入 gemini 仍然返回 "'gemini' 不是内部或外部命令，也不是可运行的程序或批处理文件"，VS Code 终端里一样。这句话就是 PATH 问题的标志：包装上了，但 Windows 完全不知道 npm 把启动器放哪了。

    Windows Command Prompt where npm install -g @google/gemini-cli finished with 577 packages and then gemini returns 'gemini' is not recognized as an internal or external command
    577 个包装完了，gemini 却报 "不是内部或外部命令"——是 PATH 症状，不是安装坏了。从 0:08 开始看
  2. 2

    问 npm 全局启动器装在哪

    运行 npm config get prefix，它会打印 npm 放全局包的目录——这里是 C:\Users\User\AppData\Roaming\npm。gemini 命令就住在这个目录里，也正是 PATH 缺的那一条。把它抄下来或留在剪贴板。

    Command Prompt running npm config get prefix and printing C:\Users\User\AppData\Roaming\npm as the folder holding the gemini launcher
    npm config get prefix 打印出 C:\Users\User\AppData\Roaming\npm——PATH 需要的目录。从 0:54 开始看
  3. 3

    在文件资源管理器里显示 AppData

    npm 目录在用户目录下的 AppData 里，Windows 默认把它藏起来。在 C:\Users\User 的文件资源管理器里打开"查看 > 显示"，勾选"隐藏的项目"——录屏就是这么做的，AppData 立刻出现在列表里。

    Windows 11 File Explorer View > Show menu with Hidden items checked so the AppData folder appears under C:\Users\User
    "查看 > 显示 > 隐藏的项目"让 AppData 出现在 C:\Users\User 下。从 1:30 开始看
  4. 4

    确认 npm 目录里确实有启动器

    进入 AppData > Roaming > npm。里面就是 gemini.cmd——gemini 命令真正调用的 Windows 命令脚本——旁边还有 gemini（给 Unix shell 用的脚本）和 node_modules。它在这儿，就证明安装没问题，坏的只是 PATH。

    File Explorer inside AppData\Roaming\npm with the gemini.cmd Windows Command Script selected, proving Gemini CLI is installed but missing from PATH
    gemini.cmd，一个 347 字节的 Windows 命令脚本，就在 AppData\Roaming\npm 里。从 2:02 开始看
  5. 5

    打开"环境变量"对话框

    在开始菜单搜"环境变量"，打开"编辑系统环境变量"，再点"环境变量"按钮。下半区是系统变量；上半区——录屏里光标指向 PATH 的地方——是你账号的用户变量。按用户安装的 npm 目录，放用户变量里正合适。

    Windows Environment Variables dialog with User variables for User, the cursor on the PATH row and System variables below, before adding the npm global folder
    环境变量对话框，光标停在用户变量的 PATH 上。从 2:38 开始看
  6. 6

    把 npm 目录加为新的 PATH 条目

    选中 PATH，点"编辑"，再点"新建"，把第 2 步的 npm 前缀粘进去——C:\Users\User\AppData\Roaming\npm，然后在每个打开的对话框上点"确定"。录屏里的列表已经有 Python、Ollama 和 VS Code 条目，新加的空行就排在它们下面；顺序对结果没有影响。

    Edit environment variable dialog for PATH with an empty new entry selected below the Python, Ollama and VS Code folders, ready for the npm global folder
    编辑环境变量对话框：新建的空 PATH 条目已选中，就等粘入 npm 目录。从 3:01 开始看

第 2 部分 — 登录失败：排掉两个 Google 账号报错

  1. 7

    认出两个 Google 账号登录报错

    PATH 修好后，gemini 能启动了，会问你用什么方式登录——选 "Login with Google"。第二段录屏展示了拦住真实登录的两个失败。第一个："Failed to login. Message: This account requires setting the GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID env var."；第二个："Failed to login. Message: Your current account is not eligible for Gemini Code Assist for individuals. To use Gemini Code Assist for individuals you must be 18 years old or older."

    Gemini CLI login errors written out verbatim in a notes app: Failed to login asking for the GOOGLE_CLOUD_PROJECT env var and Failed to login for accounts not eligible for Gemini Code Assist under 18
    两条 Failed to login 原文：GOOGLE_CLOUD_PROJECT 要求，和 18+ 资格拒绝。从 0:35 开始看
  2. 8

    不需要就别设 GOOGLE_CLOUD_PROJECT

    录屏里展示的维护者讨论帖 #13516 "Clarifying Authentication and Google Cloud Project Settings" 把何时需要这个变量说清楚了：以个人身份用免费账号、AI Pro 或 AI Ultra 登录时，不应该设它。需要它的是 Workspace 账号、Code Assist 授权席位、未成年人和不在免费额度支持地区的账号。个人套餐却设了它？删掉变量再登录。

    google-gemini gemini-cli GitHub discussion 13516 on Clarifying Authentication and Google Cloud Project Settings explaining when NOT to set GOOGLE_CLOUD_PROJECT for free AI Pro and AI Ultra accounts
    gemini-cli 讨论 #13516：免费、AI Pro 和 AI Ultra 账号何时不该设 GOOGLE_CLOUD_PROJECT。从 1:05 开始看
  3. 9

    被 Google 拒了就去做年龄验证

    "not eligible … 18 years old or older" 这个拒绝跟你的真实生日无关——跟"确认过的"生日才有关系。录屏里的账号没验证过年龄，所以 Google 显示年龄状态页："Your age isn't confirmed" 和一个蓝色的 Verify your age 按钮。走完这个流程（视频作者用的是护照），再运行 gemini 选 Login with Google——刚才还失败的登录这次成功了。

    Google Age status panel open beside the gemini-cli GitHub discussion, showing Your age isn't confirmed with a blue Verify your age button before a Gemini CLI login can succeed
    "Your age isn't confirmed" 和 Verify your age 按钮——清一次，登录就过。从 1:35 开始看

第 3 部分 — 在新终端里验证修好了

  1. 10

    在一个全新的命令提示符里重启

    PATH 改之前打开的终端还揣着旧 PATH，所以把所有窗口都关掉，开一个全新的命令提示符。输入 gemini：ASCII 的 GEMINI 横幅出现，附带"入门提示"；因为在主目录里运行，还有一条建议换到项目目录的提示——那是警告，不是报错。

    Gemini CLI ASCII banner launching successfully in Windows Command Prompt with Gemini 3 is now available, four getting-started tips and the home-directory recommendation
    第一次成功启动：命令提示符里的 GEMINI 横幅和入门提示。从 4:08 开始看
  2. 11

    再确认 VS Code 里也能用

    录屏在 VS Code 里收尾：终端开在一个真实项目目录（G:\TestProject），gemini 打印横幅、页脚显示 "no sandbox"、光标停在 "Type your message or @path/to/file"。如果 VS Code 在改 PATH 期间一直开着，先关掉重开——规则和命令提示符一样。

    VS Code terminal running gemini in the G:\TestProject folder with the GEMINI banner, a no sandbox footer and the message input ready to type
    VS Code 终端里的 G:\TestProject，GEMINI 横幅出现，输入框就绪。从 4:32 开始看

还是不行？Gemini CLI 的少见病因

PATH 和两个登录报错覆盖了大多数情况。如果之后 Gemini CLI 仍然卡住、很慢或报错，按这张清单往下排查：

  • 1与其猜，不如重装。官方故障排查文档把 PATH/npm 类损坏直接指回 npm install -g @google/gemini-cli@latest；录屏还顺手确认了系统 PATH 里 Node.js 本身还在——Node 被删或 npm 升到一半，gemini.cmd 就指向了空气。
  • 2卡在 "Initializing" 或等登录？那个画面在等 OAuth 浏览器流程走完。如果浏览器根本没弹窗，重跑 gemini，在它描述的标签页里完成 Login with Google；代理或断网会让它正好卡在这一步。
  • 3认证反复失败？登录失败的退出码是 41，缓存的 Google 凭据放在 ~/.gemini 里（oauth_creds.json 和 settings.json 并排）。删掉缓存凭据、重跑 gemini、干净地重新登录，别在坏会话上反复重试。
  • 4OAuth 压根走不通？换方式。认证对话框的第三个选项是来自 Google AI Studio 的 Gemini API key：把它导出为 GEMINI_API_KEY，CLI 就完全跳过浏览器登录。文档推荐首选 Google 登录，但 API key 有独立免费额度，也没有项目和年龄要求。
  • 5模型权限或配额报错？关联了 Workspace 的 Gmail 账号可能激活不了免费 Code Assist 额度（"Request contains an invalid argument"）——官方文档给的出路是：把 GOOGLE_CLOUD_PROJECT 设成真实项目 ID，或者改用 API key。免费额度会重置；付费的 AI Pro/Ultra 额度更高。
  • 6偏偏只有 VS Code 里不行？还是那个旧终端规则：VS Code 在启动那一刻继承 PATH，改 PATH 之前开的窗口永远看不到 npm 目录。关掉重开 VS Code（至少把它的终端杀掉），再试 gemini。

以上都对不上？看看 CLI 自己记了什么：日志和设置都在 ~/.gemini 目录下，加 --verbose 重跑会输出更多细节；官方故障排查页的最后一步和维护者说的一样——先搜 gemini-cli 的 GitHub issue，再带上版本号和完整报错开新 issue。

Gemini CLI 不能用？常见问题

相关指南

Gemini CLI 沙箱Google Antigravity CLI 教程Gemini CLI 替代品对比