Gemini CLI 装不上、命令找不到、MODULE_NOT_FOUND 怎么解决
装个 CLI 工具本该是最简单的一步，但它偏偏是劝退率最高的一步。Gemini CLI 的安装期问题主要是三类，官方 troubleshooting 都有明确处理。
这篇按类别过一遍，并且专门指出其中一条完全可以无视的警告——很多人在那上面白白折腾。
一、command not found：装是装了，但找不到
现象：装完之后敲 gemini，回你一句命令找不到。
官方说明的成因很直接：没装好，或者不在系统 PATH 里。
处理办法取决于你怎么装的，官方分了两种情况：
全局安装的
检查 npm 的全局 bin 目录在不在 PATH 里。
先看看那个目录在哪：
npm bin -g
或者：
npm config get prefix
拿到路径之后，确认它在 PATH 中：
echo $PATH
Windows PowerShell：
$env:PATH
不在的话，把它加进 shell 配置文件（.bashrc、.zshrc 等），然后重开终端。
更新的命令官方给的是：
npm install -g @google/gemini-cli@latest
从源码跑的
官方提醒确认调用方式是对的，例子是：
node packages/cli/dist/index.js ...
更新的话，pull 最新代码之后重新构建：
npm run build
一个容易忽略的点
command not found 和「装失败了」是两回事。装的过程可能完全成功，只是那个可执行文件放的位置不在你的搜索路径里。
判断方法：
npm ls -g --depth=0
能看到 @google/gemini-cli，说明装上了，问题就在 PATH。
二、MODULE_NOT_FOUND 或 import 报错：依赖或构建的问题
官方说明的成因：依赖没装好，或者项目没构建。
官方给的处理是三步，按顺序做：
npm install—— 确保依赖都在npm run build—— 编译项目npm run start—— 验证构建成功
第三步别省。构建过程可能报了错但你没注意，直接去跑就会撞上莫名其妙的模块找不到。
这类问题在从源码跑的场景下最常见。全局安装的用户一般不会撞上——除非安装过程中途失败了，留下一个不完整的状态。那种情况下最干净的做法是卸载重装：
npm uninstall -g @google/gemini-cli
npm install -g @google/gemini-cli@latest
三、那些 npm 弃用警告：可以直接忽略
装或更新的时候，可能会看到：
npm WARN deprecated node-domexception@1.0.0
npm WARN deprecated glob
这条是本文最值得说的一条，因为它根本不是问题。
官方 troubleshooting 对它的说明是：这些警告的成因是某些依赖（或者它们的子依赖，比如 google-auth-library）用了较老版本的包。而由于 Gemini CLI 要求 Node.js 20 或更高版本，平台的原生特性（比如原生的 DOMException）已经在用了，所以这些警告纯粹是提示性的。
官方的原话意思很明确：这些警告无害，可以安全忽略；安装或更新会正常完成并正常工作，不需要做任何事。
为什么要专门讲这条？因为 WARN deprecated 这种字眼看起来很吓人，很多人会：
- 去手动升级那些子依赖（可能反而搞坏依赖树）
- 反复卸载重装（浪费时间，警告照样在）
- 以为安装失败了，转而怀疑别的地方
看到这两条警告，什么都别做，接着用。
顺带记住那个 Node 版本要求：Node.js 20 或更高。如果你的 Node 版本太低，那才是真问题——而且报错通常不会明说是版本问题，可能表现为各种语法错误或模块加载失败。装之前先看一眼：
node -v
四、装完之后立刻会撞上的那一类
安装过了，下一步就是登录，而登录是另一个高频卡点。这里只列出来让你有个预期，处理办法要看对应的专门内容：
| 报错 | 一句话成因 |
|---|---|
You must be a named user on your organization's...Standard edition subscription | 环境里有 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID，触发了组织订阅校验 |
Failed to sign in. Message: Request contains an invalid argument | Workspace 账号或关联 Gmail 的 GCP 账号激活不了免费档 |
Failed to sign in...not currently available in your location | 所在地区不支持 |
UNABLE_TO_GET_ISSUER_CERT_LOCALLY | 企业网络拦截 TLS，先试 NODE_USE_SYSTEM_CA=1 |
第一条是这里面最反直觉的——个人用户也会撞上，而且报错文本会把你往「去找管理员」的死路上引。真因是环境变量，清掉就好。
五、CI 环境里的一个坑
如果你在 CI 或者容器里装完之后发现它「不出提示符」，官方对这条有明确说明。
成因是底层用的 is-in-ci 包会检测这几个东西：CI、CONTINUOUS_INTEGRATION，以及任何以 CI_ 开头的环境变量。检测到任何一个，就判定这是非交互环境，于是不进交互模式。
坑在于最后那条：你自己定义的 CI_TOKEN、CI_ENV 之类，哪怕跟 CI 一点关系没有，也会触发。
官方给的办法是临时取消它：
env -u CI_TOKEN gemini
还有一个相关的：项目 .env 里设 DEBUG=true 不生效。官方说明是 DEBUG 和 DEBUG_MODE 会被自动从项目 .env 里排除，防止干扰行为。要开调试，用 .gemini/.env，或者调整 settings.json 里的 advanced.excludedEnvVars 少排除一些变量。
六、全局安装还是从源码跑
官方 troubleshooting 在好几条里都按这两种方式分开给处理，说明它们的问题类型确实不一样。选之前值得知道各自会遇到什么。
全局安装（npm install -g @google/gemini-cli）
- 更新简单：
npm install -g @google/gemini-cli@latest - 典型问题：PATH 配置、npm 全局目录的权限
- 适合：只想用，不打算改代码
从源码跑
- 需要自己
npm install+npm run build - 典型问题：依赖没装全、没构建、调用方式不对（
MODULE_NOT_FOUND基本都出在这边） - 更新要 pull 之后重新
npm run build——忘了重新构建是这条路上最常见的坑，你 pull 了新代码，跑的还是旧的产物 - 适合：要改代码、要跟最新提交、或者要调试
大多数人应该选全局安装。 从源码跑的唯一充分理由是你要动代码或者跟主干——否则你只是给自己多添了一类会出问题的环节。
一个常见的混乱是两种方式共存：以前从源码跑过，后来又全局装了一份，结果 gemini 指向的是哪个自己都不清楚。用这个确认：
which gemini
Windows：
where gemini
如果输出了多条路径，那就是有多份——按 PATH 顺序，排在前面的那个生效。这能解释「我明明更新了怎么还是老版本」。
七、更新与卸载
更新：
npm install -g @google/gemini-cli@latest
确认版本：
gemini --version
彻底重装（安装中途失败、留下不完整状态时用）：
npm uninstall -g @google/gemini-cli
npm install -g @google/gemini-cli@latest
什么时候该优先考虑升级：如果你撞上的是那种「看起来像程序内部出错」的报错——比如某个属性读不到、某个模块加载不了——升级的性价比通常比逐条排查高。这类问题往往是边界情况没处理好，后续版本会加上判空和兜底。
反过来，登录类、额度类、沙箱类的问题升级基本没用，因为那些是配置和策略层面的，跟版本无关。
八、安装期问题的排查顺序
node -v—— 确认 Node.js 20 或更高npm ls -g --depth=0—— 确认包确实装上了- 装上了但命令找不到 → PATH 问题，检查
npm bin -g的路径在不在PATH里，加完重开终端 - 报
MODULE_NOT_FOUND→npm install→npm run build→npm run start验证 - 看到
npm WARN deprecated→ 无视它 - CI 里不进交互模式 → 查有没有
CI_开头的环境变量，用env -u临时取消 - 装完登录报错 → 那是另一族问题，先看是不是环境里有
GOOGLE_CLOUD_PROJECT
九、总结
command not found通常是 PATH 问题，不是装失败。先用npm ls -g --depth=0分清。MODULE_NOT_FOUND按npm install→npm run build→npm run start三步走，第三步别省。npm WARN deprecated node-domexception和glob是无害的，官方明说可以忽略——别去手动升级子依赖。- Node.js 要 20 或更高，版本太低的报错往往不会明说是版本问题。
- CI 里不进交互模式，可能是任何
CI_开头的变量引起的，用env -u绕开。 - 装完紧接着的登录报错是另一族，最常见的真因是环境里的
GOOGLE_CLOUD_PROJECT。
本文所引官方内容来自 google-gemini/gemini-cli 仓库自带的 troubleshooting 文档，核对日 2026-08-08。包名、命令与版本要求会变化，以官方文档为准。