安装、终端与运行环境排障

同一个错误可能来自 CLI 安装、源码构建、终端模式或实际工具执行。先确认失败在哪一层，再采取与安装来源对应的修复。

找不到 gemini 命令

确认 CLI 确实安装，并检查包管理器全局可执行目录是否在 PATH。npm 全局安装的更新方式为：

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

Homebrew 等安装应按相应安装来源管理，见安装与升级。从源码运行则需要在 Gemini CLI 源码仓库中完成构建，官方给出的入口示例为 node packages/cli/dist/index.js ...；不要在任意业务仓库运行 CLI 自身的构建流程。

模块缺失和 ESM 错误

MODULE_NOT_FOUND 或 import 错误可能表示源码依赖未准备好或产物未构建。官方源码排障顺序为 npm install、npm run build、npm run start，前提是位于对应源码项目。

ERR_REQUIRE_ESM 反映 CommonJS/ES Modules 不匹配。FAQ 提到核对 package.json 的 type: module 和 tsconfig.json 中兼容的模块模式，例如 NodeNext。先检查具体报错指向的包与工程配置，不应为修复全局 CLI 而随意改变业务项目的模块体系。

没有出现交互输入框

官方排障说明底层 CI 检测会检查 CI、CONTINUOUS_INTEGRATION 以及 CI_ 前缀变量。如果开发终端中意外继承 CI_TOKEN，可能被当成非交互环境。

在该变量确实不影响本次 CLI 运行时，可用 POSIX Shell 临时移除：

env -u CI_TOKEN gemini

实际 CI 自动化则应使用无头模式，并处理输出与退出状态。

DEBUG 与普通 .env

DEBUG、DEBUG_MODE 默认从普通项目 .env 中排除。按需改用 .gemini/.env，或核对 advanced.excludedEnvVars；其加载优先级与信任规则见环境配置。也可以通过 --debug 开启 CLI 调试，交互中 F12 查看调试控制台。

工具失败与权限

EADDRINUSE 表示端口已有进程占用。先识别实际服务，再为 MCP 配置其他端口或按需停止原服务，不能直接假定应结束某个无关进程。

Operation not permitted 或 Permission denied 要同时核对真实文件权限、路径和沙箱范围。Shell 工具失败时，可先用最小命令在相同 Shell 环境复现。

Windows 默认环境不包含所有 Unix 命令。例如 chmod 不能直接当作原生 Windows 权限工具；按环境选择 Windows 权限工具或 Git Bash/WSL，不把平台差异误判为模型错误。

安装警告与失败区分

官方将 node-domexception 和旧 glob 的部分 deprecated 提示解释为依赖链警告。这些提示本身不表示安装失败；仍以安装退出状态和实际错误为准，不把所有包含 warning 的输出都忽略。