module not found 报错定位检查清单

这份清单用于处理 module not found、Cannot find module、Can't resolve 这类错误。完整解释见 module not found 报错怎么定位文件。排查目标是先判断缺的是文件、包还是别名配置。

适合谁

适合在前端项目里遇到模块找不到，但不知道该看路径、依赖还是配置的新手。你可以把清单填完，再决定怎么修。

也适合项目诊断。客户给你一张构建失败截图时，你可以先要求完整报错和仓库上下文，而不是直接猜。

不适合谁

不适合看到缺包就直接安装最新版本的人。版本不匹配可能引入新的问题。

也不适合没确认客户授权就处理私有包、私有 registry 或缺失源码的人。这些需要客户侧补材料或权限。

风险提醒

不要为了消除报错而删除导入或组件。这样会让页面缺功能。也不要把私有包 token、客户仓库路径、内部 registry 地址公开到记录里。

如果问题来自客户漏提交文件或私有依赖访问权限，写成客户待确认事项，不要伪造替代文件。

具体步骤

1. 报错原文

• 完整命令：
• 完整报错：
• 缺失模块名：
• 导入文件：
• 本地还是 CI：
• 使用框架：

不要只写“模块找不到”。模块名和导入位置才是关键。

2. 判断类型

• 本地相对路径：
• 绝对路径别名：
• npm 包：
• 私有包：
• 图片或静态资源：
• 生成文件：

类型不同，修法不同。先分类，再处理。

3. 本地文件检查

• 文件是否存在：
• 目录是否正确：
• 文件名大小写是否一致：
• 扩展名是否匹配：
• index 文件是否存在：
• 文件是否被 git 忽略：

大小写问题特别容易在本地没事、部署失败时出现。

4. 依赖检查

• package.json 是否声明：
• 锁文件是否同步：
• 使用 npm、pnpm 还是 yarn：
• 是否需要私有 registry：
• 是否需要客户授权：

不要在没确认包管理器时随便安装。

5. 别名配置

• tsconfig.json 或 jsconfig.json：
• Vite 配置：
• Webpack 配置：
• Next.js 配置：
• 测试环境配置：
• CI 是否读取同一配置：

如果只有测试或 CI 失败，可能是某个环境没有读取 alias。

6. 验证结果

• 修复文件：
• 修改原因：
• 运行命令：
• 结果：
• 是否还有新报错：
• 是否需要客户补材料：

记录结果能避免一边修一边忘。

最低交付记录

最低记录包含：缺失模块、导入文件、原因分类、修复动作、验证命令、客户待确认事项。客户看完后应该知道问题是代码路径、依赖包，还是权限材料。

如果只是客户缺少私有包授权，交付可以是诊断报告和待办清单，不一定是代码修改。

日志摘录格式

给客户或队友看时，不要复制整段构建日志。更好的摘录方式是：缺失模块名、引用它的文件、第一条关键错误、触发命令、你判断的原因类型。这样信息足够，又不会把无关日志和敏感路径扩散。

如果日志里有客户仓库名、内部目录、私有 registry、token 或邮箱，先脱敏。脱敏后保留结构，例如把真实包名改成 @private/ui-kit，把真实路径改成 src/components/...。这样别人仍能理解问题，但不会暴露客户信息。

摘录最后加一句下一步：是你继续改代码，还是客户补权限，还是需要人工复核。没有下一步的日志摘录，只是资料堆积。

复测字段

修完后补三项：复测命令、复测环境、复测结果。如果本地通过但 CI 仍失败，要继续记录差异，比如 Node 版本、包管理器、大小写敏感、私有依赖权限。这样后续不会把同一个问题重复排查。

如果复测需要客户补权限，就写“等待客户补权限后复测”。这句话能把你的工作和外部等待拆开。

客户待办示例

常见客户待办包括：补交漏掉的组件文件、确认私有包是否可访问、添加私有 registry 权限、说明项目使用 npm 还是 pnpm、提供 CI 失败日志、确认是否允许新增依赖。每一项都要写清负责人。

不要把“客户需要补材料”写成“我明天继续修”。更准确的写法是：明日等待客户提供私有包访问方式，收到后先运行安装命令，再复测 build。这样记录更清楚，也不会把授权问题变成你的未完成事项。

CTA：下一步

把这份清单复制到排查记录里，先填缺失模块和导入文件。需要拆报错用 报错解释器，需要整理客户说明看 模板库。

免责声明

本文是学习和排查流程，不构成法律、安全或职业承诺。真实客户项目需要结合仓库权限、依赖来源、私有包授权、构建环境和人工复核判断。