故障排查

排查 Gemini CLI 不要先重装。先按错误类型定位：认证、网络、安装、配置、sandbox、CI。

排障顺序要从“当前命中了哪个 gemini、用了什么认证、读了哪些配置”开始。直接重装往往会保留旧配置，反而看不出根因。

排查总览

错误类型	第一检查项	常见根因
登录失败	账号类型、`GOOGLE_CLOUD_PROJECT`、认证方式	Workspace / Cloud 账号 entitlement 或项目变量不匹配
证书错误	企业代理、Node CA 配置	TLS inspection 没有把公司根证书交给 Node
command not found	`command -v gemini`、npm global bin、PATH	安装来源和 shell PATH 不一致
import / module 错误	依赖、build、源码入口	源码环境未安装或未构建
sandbox 拒绝	写入路径、被调用命令、sandbox 类型	试图访问项目外或受限路径
CI 不交互	`CI` / `CONTINUOUS_INTEGRATION` / `CI_*` 环境变量	TUI 被判定为非交互环境

认证错误

如果看到 Gemini Code Assist Standard subscription 相关错误，先检查：

先用 echo $GOOGLE_CLOUD_PROJECT 和 echo $GOOGLE_CLOUD_PROJECT_ID 检查环境变量。

个人账号误设置这些变量，可能触发组织订阅检查。个人用户可以先 unset；组织用户需要管理员分配 entitlement。

地区不可用

如果登录提示当前账号所在地区不可用，需要查 Gemini Code Assist 支持地区。这个问题不是本地配置能修复的。

证书错误

企业网络或代理可能拦截 TLS，导致：

典型报错包括 UNABLE_TO_GET_ISSUER_CERT_LOCALLY 或 unable to get local issuer certificate。

官方 troubleshooting 的直接做法是把企业根证书交给 Node：

export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.crt

如果公司网络要求统一代理，还要同时检查 shell、npm、Node 和 Gemini CLI 运行环境是否都走同一代理。不要把证书错误误判成 Gemini 账号错误。

`gemini` command not found

检查安装方式和 PATH：

先看全局包、npm prefix 和 PATH：npm list -g @google/gemini-cli、npm config get prefix、echo $PATH。

如果是全局安装，更新命令是：

全局安装的更新命令是 npm install -g @google/gemini-cli@latest。

如果是源码运行，要确认使用的是源码入口，并且已经重新 build。普通用户教程不应默认走源码入口。

`MODULE_NOT_FOUND` 或 import 错误

这类错误通常发生在源码开发或依赖损坏场景。先按官方建议恢复最小链路：

npm install
npm run build
npm run start

如果你只是普通用户，不要在业务项目里反复改 package.json 来修 Gemini CLI；先用全局安装或 npx @google/gemini-cli 在空目录复现。

MCP 端口占用

EADDRINUSE 表示 MCP server 要绑定的端口已被占用。处理方式是停止占用进程，或给 MCP server 换端口。

Sandbox 权限错误

Operation not permitted 或 Permission denied 在 sandbox 下常见。先判断 Gemini CLI 是否试图写项目外路径、系统临时目录以外路径，或调用被限制的命令。

CI 环境不进交互模式

如果环境变量里存在 CI、CONTINUOUS_INTEGRATION 或 CI_ 前缀变量，CLI 可能判断为非交互环境。

临时规避：

临时规避可以用 env -u CI_TOKEN gemini。

DEBUG 不从项目 `.env` 生效

官方 troubleshooting 提到，项目 .env 里的 DEBUG 和 DEBUG_MODE 会被自动排除，避免干扰 Gemini CLI 行为。要打开 debug，优先使用 .gemini/.env，或明确调整 settings.json 里的 advanced.excludedEnvVars。

退出码

常见退出码：41 是认证错误，42 是输入错误，44 是 sandbox 错误，52 是配置错误，53 是 turn limit 错误。

退出码	含义	排查入口
`41`	认证错误	登录方式、账号、project、API key
`42`	输入错误	headless 参数、stdin、非交互输入
`44`	sandbox 错误	Docker / Podman / Seatbelt、写入路径
`52`	配置错误	全局和项目 `settings.json`
`53`	turn limit	任务拆分、上下文、自动化循环

最小复现

排障记录要能复跑：

在空目录执行同一命令。
记录 gemini --version 和 command -v gemini。
标注认证方式，不贴 token。
临时移开项目 .gemini/ 后复测。
如果涉及 MCP、hooks 或 shell，单独验证底层命令是否可运行。