Next.js本地正常部署Vercel提示找不到组件模块如何解决

问题现象 #

• 本地开发环境运行Next.js项目一切正常，部署到Vercel平台时提示找不到模块，报错截图如下：
  
• 项目中已创建components文件夹，每个组件单独存放在对应子文件夹下，同时创建了index文件做组件统一导出。head文件夹真实存在，内部包含index.tsx及相关组件文件，也已经完成了对应组件的导出配置，但部署时依然触发上述报错。
• components文件夹目录结构如下：
  

修复方法 #

这个问题的核心诱因是本地Windows/macOS系统文件路径默认大小写不敏感，Vercel构建使用的Linux系统对路径、文件名大小写严格校验，本地写错大小写不会触发异常，到线上构建时就会直接判定模块不存在，按以下步骤排查即可：

• 全局核对所有导入语句的路径大小写，确保和实际文件夹、文件名完全一致
  比如实际文件夹名为小写head，导入时写成@/components/Head本地运行不会报错，但Linux环境下会直接识别为路径不存在；反之文件夹名为大写Head，导入写小写路径也会触发相同报错。
• 检查多层导出的路径配置
  先核对components/head/index.tsx内部的导入导出路径没有大小写错误，再核对components根目录下做统一导出的index文件，引用head组件的路径大小写和实际目录完全匹配。
• 检查.gitignore规则
  确认components目录、head目录没有被.gitignore的规则命中忽略，如果目录被git忽略，Vercel拉取代码时不会获取到对应文件，自然会报模块找不到。
• 清理缓存重新部署
  上述问题修复完成后，进入Vercel对应项目的控制台，选择重新部署，勾选清除构建缓存选项后触发构建即可。

本地快速验证方式：Windows用户可以在WSL（Linux子系统）环境下进入项目目录执行npm run build，如果WSL环境下构建能正常通过，Vercel部署时基本不会再出现这类路径相关的报错。

内容的提问来源于stack exchange，提问作者Hassan Sheikh