Gemini API在Node.js中的依赖问题：CLI安装与模块加载故障排查全指南
遇到“Cannot find module”这类报错，说穿了其实就是Node.js的模块依赖链条在某个环节断了。很多开发者第一反应是直接重装，但问题往往会复现。正确的做法是像排查电路故障一样，按顺序来，每一步都别跳。
当你运行 gemini-cli 或者 require('@google/generative-ai') 却收到“Cannot find module”，甚至直接提示找不到 npm-cli.js 时，先别急着怀疑代码写错了。这通常意味着环境层级出了毛病——可能是缓存坏了、文件被误删，或是模块加载方式不匹配。下面这套排查流程，从最底层开始一步步往上修。
先确认Node.js和npm本身能否正常工作
打开终端，敲下第一组命令：
node -v && npm -v
如果系统告诉你 'node' is not recognized，或者直接返回空，那就说明Node.js的安装路径没有被正确加载到环境变量（PATH）里。这个时候先别管包管理的事，去检查一下系统变量里是否包含Node.js的根目录，比如 C:\Program Files\nodejs，同时确认这个路径下确实存在 node.exe 和 npm.cmd 两个文件。路径不对，后续的一切操作都是白搭。
如果两个命令都正常返回版本号（比如 v20.19.2 和 v10.8.2），但执行 npm install @google/generative-ai 依然失败，那问题就出在模块的解析路径或缓存污染上了。进入下一步。
清理损坏的node_modules和npm全局状态
方法一：仅清理当前项目依赖（推荐优先尝试）
在项目的根目录下跑这三步：先删除 node_modules 和锁文件，再强制清理npm缓存，最后重新安装。
rm -rf node_modules package-lock.json → npm cache clean --force → npm install
这套组合拳能解决绝大多数项目级别的MODULE_NOT_FOUND错误。如果缓存目录本身存在权限问题，或者文件被锁住了，这一步往往就能修复。
方法二：重置npm全局配置（当全局命令失效时必做）
先跑 npm config get prefix，确认输出的路径存在且可写。如果显示的是 C:\Users\XXX\AppData\Roaming\npm，就需要右键这个文件夹 → 属性 → 安全 → 编辑 → 给“Users”勾选“完全控制”权限。否则用npm install -g安装全局工具时，会因为权限不足而静默失败。
【关键前提】一定要确认 npm config get cache 指向的缓存目录没有包含空格，也不要放在 Program Files (x86) 这类系统保护路径下。Node.js对带空格的路径解析存在不稳定因素，非常容易触发MODULE_NOT_FOUND。稳妥的做法是执行以下命令，重置prefix和cache配置：
npm config delete prefix → npm config delete cache → 重启终端 → npm install -g npm（强制重装npm自身）
修复npm核心文件缺失的问题（针对npm-cli.js报错）
如果报错信息里出现了 node_modules\npm\bin\npm-cli.js，那说明 node_modules/npm/ 这个目录根本不存在。这通常是因为手动删除 node_modules 时，不小心连npm自身的包也一起删了；或者使用了非标准的安装方式导致文件未被正确写入。
第一步：确认错误路径中的缺失文件
先看清楚报错里指示的完整路径。如果确实验证了node_modules/npm/bin/npm-cli.js 不存在，那就进入下一步。
第二步：手动补全npm目录
访问 npm最新版注册表，获取最新版npm tarball URL。用浏览器下载 npm-*.tgz 文件，然后解压。进入解压后的 package/ 目录，把里面的npm文件夹整个复制到你的Node.js安装目录下的 node_modules 里。路径通常是 C:\Program Files\nodejs\node_modules\npm。
第三步：验证修复效果
在任意路径下运行 npm --version。如果成功返回版本号，说明 npm-cli.js 已被正确加载。这时再执行 npm install -g @google/generative-ai，CLI工具就能正常安装了。
解决@google/generative-ai模块的加载失败
方法1：确认安装方式与使用场景匹配
这是最容易踩坑的地方。如果你的项目是CommonJS风格（package.json中没有 "type": "module"），想通过 require('@google/generative-ai') 调用，那么模块必须本地安装：
npm install @google/generative-ai
如果用 npm install -g @google/generative-ai 全局安装，它只提供 gemini 命令行工具，并不会把模块注入到你的 require 路径里。这是很多新手翻车的根源。
方法2：绕过ESM/CJS混合陷阱
如果你的项目启用了ESM（package.json中包含了 "type": "module"），那直接用 require 必然报错。切换到ESM的导入语法：
import { GoogleGenerativeAI } from '@google/generative-ai';
同时还得确认 node_modules/@google/generative-ai 目录真实存在，并且内部有 dist/index.mjs 文件。如果缺少这个文件，说明安装过程中网络中断或文件被写坏了，解决办法就是删掉这个目录，重新跑 npm install。
方法3：强制指定NODE_PATH（仅Windows/Linux环境必要）
如果你试了上述所有方法，require() 依旧找不到模块，可以临时设置环境变量来强制指定模块搜索路径。
Windows CMD：set NODE_PATH=%APPDATA%\npm\node_modules
macOS/Linux：export NODE_PATH=$HOME/.npm-global/lib/node_modules
设置完马上执行 node -e "console.log(require('@google/generative-ai'))"，如果能输出构造函数，那就说明之前的模块解析路径没被正确加载。这个方案只是临时补救，长久之计还是要把全局模块安装到标准路径下，并确保环境变量正确。