“Cannot find module”错误需按顺序排查：先验证node/npm版本，再清理缓存与node_modules，修复npm-cli.js缺失，最后区分全局/本地安装及ESM/CJS加载方式。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当你在Node.js项目中执行gemini-cli命令或require('@google/generative-ai')时提示“Cannot find module”、报错找不到npm-cli.js或generative-ai，说明环境依赖链已断裂，必须立即定位并修复。
验证Node.js与npm基础状态
打开终端，依次执行两行命令：
node -v && npm -v
若任一命令报'node' is not recognized或返回空，说明PATH未正确加载Node.js安装路径；此时不要继续后续操作，先检查系统环境变量中是否包含Node.js根目录（如C:\Program Files\nodejs\），且该路径下存在node.exe和npm.cmd两个可执行文件。
若版本号正常输出（如v20.19.2和v10.8.2），但运行npm install @google/generative-ai仍失败，则问题出在模块解析路径或缓存污染，进入下一步。
清理损坏的node_modules与npm全局状态
方法一：仅清理当前项目依赖（推荐优先尝试）
在项目根目录下执行：
rm -rf node_modules package-lock.json → npm cache clean --force → npm install
方法二：重置npm全局配置（当gemini-cli等全局命令失效时必做）
先执行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。
执行：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自身包，或使用了非标准安装方式。
第二步：手动补全npm目录
Miller (mlr) 是一个命令行工具，用于查询、整形和重新格式化名称索引数据，如 CSV、TSV、JSON 和 JSON Lines。它将 awk、sed、cut、join 和 sort 的功能整合到一个专为结构化数据处理而构建的单一工具中。
访问https://registry.npmjs.org/npm/latest获取最新版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项目（无"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会直接报错。改用：
import { GoogleGenerativeAI } from '@google/generative-ai';
且确保node_modules/@google/generative-ai目录真实存在，其内部有dist/index.mjs文件。若不存在，说明安装中途被中断，删掉该目录后重试npm install。
方法3：强制指定NODE_PATH（仅Windows/Linux必要）
当require()始终无法定位模块时，在终端执行：
set NODE_PATH=%APPDATA%\npm\node_modules（Windows CMD）
或
export NODE_PATH=$HOME/.npm-global/lib/node_modules（macOS/Linux）
然后立即运行node -e "console.log(require('@google/generative-ai'))"验证是否输出构造函数。
