Codex ERR_MODULE_NOT_FOUND 模块找不到怎么办这个错误一般出现在本地跑 Codex、CLI 工具、Node.js 脚本或者项目里的 agent 工具链时。终端里通常会看到ERR_MODULE_NOT_FOUND后面跟着一段Cannot find package或Cannot find module。遇到它先别急着重装系统优先查三件事当前目录对不对、依赖有没有装、模块名或导入路径是不是写错了。一、常见错误现象比较典型的报错长这样### token云桥中转 0029.org ### Error [ERR_MODULE_NOT_FOUND]: Cannot find package xxx imported from /Users/demo/project/index.js at packageResolve (node:internal/modules/esm/resolve:...) at moduleResolve (node:internal/modules/esm/resolve:...)也可能是这种Error [ERR_MODULE_NOT_FOUND]: Cannot find module /Users/demo/project/src/config imported from /Users/demo/project/src/index.js如果你是在运行 Codex 相关命令时遇到比如codex npm run codex node ./scripts/codex.js本质上还是 Node.js 在加载依赖或本地文件时失败。不要只盯着 Codex本地 Node 环境和项目依赖更值得先排查。二、先判断是哪一类模块找不到1. 第三方包找不到如果报错里是Cannot find package openai Cannot find package xxx/xxx Cannot find package dotenv这种通常说明依赖没安装、安装到了别的目录或者 lock 文件和当前环境不一致。2. 本地文件找不到如果报错里出现的是本地路径Cannot find module /project/src/config Cannot find module /project/lib/client多数是导入路径写错、文件扩展名缺失、大小写不一致或者 ESM 模式下没有按规则写完整路径。3. 全局命令和项目依赖混用有些人是全局装了 Codex 或相关 CLI但项目本身没装依赖也有人在 A 项目执行了 B 项目的命令。这类问题报错看起来像模块缺失实际是执行位置和依赖位置不一致。三、按顺序排查和修复步骤 1确认当前目录先看你是不是在项目根目录。项目根目录一般能看到package.json。pwd ls cat package.json如果没有package.json先切到正确目录cd /path/to/your/project很多ERR_MODULE_NOT_FOUND都是因为在上一级目录或者错误目录执行命令导致的。步骤 2重新安装依赖如果项目里有package-lock.json优先用npm ci它会严格按 lock 文件安装npm ci如果没有 lock 文件或者你只是本地调试可以用npm install使用 pnpm 或 yarn 的项目不要混用包管理器pnpm install # 或 yarn install混用之后可能出现node_modules结构异常尤其是 monorepo 项目更容易踩坑。步骤 3确认缺失包是否真的在 dependencies 里假设报错提示找不到openai检查一下npm ls openai如果输出类似(empty)或报缺失就安装它npm install openai如果是开发脚本用到的包也可以装到 devDependenciesnpm install -D dotenv tsx typescript注意运行时需要的包不要随便放到devDependencies部署环境如果只安装生产依赖可能又会复现模块找不到。步骤 4检查 Node.js 版本Codex 相关工具和新版 SDK 往往依赖较新的 Node.js。先看版本node -v npm -v建议至少使用 Node.js 18 或 20。如果项目里有.nvmrc按项目指定版本切换cat .nvmrc nvm use没有安装对应版本时nvm install 20 nvm use 20版本太旧时报错不一定直接提示语法不支持有时也会表现为模块解析失败。步骤 5修正 ESM 导入路径如果你的package.json里有{ type: module }那么 Node.js 会按 ESM 规则解析模块。本地文件导入时扩展名通常要写完整。容易出错的写法import config from ./config; import client from ./lib/client;建议改成import config from ./config.js; import client from ./lib/client.js;如果你写的是 TypeScript运行方式也要对应。比如用tsx直接跑npx tsx src/index.ts不要一边写 TS 源码路径一边用普通node直接运行未编译文件。步骤 6检查大小写问题macOS 默认文件系统对大小写不敏感Linux 服务器通常敏感。本地能跑、服务器报ERR_MODULE_NOT_FOUND很可能是大小写不一致。例如文件名是src/Config.js代码里却写import config from ./config.js;在 Linux 上这就是两个不同文件名。修复方式是统一文件名和导入路径推荐全部使用小写加短横线或小写驼峰别混着来。步骤 7清理后重装如果依赖树已经乱了可以清理一次。npm 项目rm -rf node_modules package-lock.json npm installpnpm 项目rm -rf node_modules pnpm-lock.yaml pnpm install团队项目里不要随便删除 lock 文件后提交。更稳妥的做法是先删除本地node_modules保留 lock 文件再安装rm -rf node_modules npm ci四、Codex 场景下还要看 API 配置如果模块问题修好了但 Codex 继续报连接、鉴权或模型调用错误就要检查环境变量。常见配置一般在.env或终端环境里echo $OPENAI_API_KEY cat .env本地调试时我一般会把依赖问题和接口问题分开排。模块找不到先解决 Node 依赖能正常启动后再处理 API Key、Base URL、模型名这些配置。需要稳定测试不同模型或中转接口时可以顺手看一下 token云桥AI中转站 0029.org适合拿来做开发阶段的连通性验证省得把依赖错误和接口错误混在一起判断。五、修复后的验证方式修复完不要只看“没报错”建议按下面顺序验证。1. 验证依赖是否存在npm ls openai npm ls dotenv把openai、dotenv替换成你报错里真正缺失的包名。2. 验证项目脚本npm run build npm run start如果是 Codex 脚本npm run codex或者直接执行入口文件node ./src/index.js3. 验证导入路径可以写一个最小测试文件只导入出错模块import dotenv/config; import OpenAI from openai; console.log(modules ok);保存为check.js后运行node check.js如果这里没问题说明基础依赖是好的后续再查业务代码路径。六、避免以后反复出现项目统一包管理器npm、pnpm、yarn 不要混用。提交 lock 文件部署时按 lock 文件安装依赖。ESM 项目本地导入写完整扩展名例如./client.js。文件名大小写保持一致尤其要考虑 Linux 部署环境。在 README 里写清楚 Node.js 版本最好提供.nvmrc。Codex 相关配置单独放在.env.example不要把 API Key 写进代码。总结ERR_MODULE_NOT_FOUND看起来像 Codex 报错实际大多是 Node.js 依赖解析问题。排查时按“目录是否正确、依赖是否安装、Node 版本是否匹配、导入路径是否符合 ESM 规则、大小写是否一致”这个顺序走通常很快能定位。修复后再用npm ls、npm run build和最小导入脚本验证能避免问题在部署环境里再次出现。