React编译报错：Card.js与磁盘对应路径名称不匹配如何排查

报错信息 #

ERROR: Failed to compile.

./src/places/components/PlaceList.js
Cannot find file: 'Card.js' does not match the corresponding name on disk: '.\src\Shared\components\UIElements\shared'.

问题背景 #

React 项目开发过程中触发上述编译报错，多次检查文件导入路径后仍未定位报错原因，不清楚问题触发逻辑，项目文件结构参考：

根因说明 #

该报错由模块解析路径与磁盘实际路径不匹配触发，React 项目使用的 Webpack 构建工具严格校验导入路径的大小写、文件/文件夹层级，和本地文件系统的宽松规则不同，只要路径存在大小写差异、层级指向错误（指向文件夹而非目标文件）就会抛出该错误。

排查解决步骤 #

• 修正路径大小写错误
  打开./src/places/components/PlaceList.js文件，找到Card组件的导入语句，核对路径中所有文件夹名的大小写：报错信息中路径最后一段为shared，如果导入语句中写了大写开头的Shared作为某级目录名，直接修改为和磁盘实际命名完全一致的大小写格式。
• 修正路径层级错误
  报错提示当前导入路径最终指向了.\src\Shared\components\UIElements\shared这个文件夹，而非目标Card.js文件，说明导入路径多写了一层目录：
  1. 先确认Card.js的实际存放位置，通常该组件路径为src/shared/components/UIElements/Card.js
  2. 删除导入路径中多余的/shared层级，确保路径最终指向Card.js文件本身，而非同名文件夹
     错误导入示例：import Card from '../../Shared/components/UIElements/shared/Card'
     正确导入示例：import Card from '../../shared/components/UIElements/Card'
• 检查统一导出配置
  如果是通过目录下的index.js做组件统一导出，打开对应目录的索引文件，核对Card组件的导出路径是否存在大小写错误、多余层级问题。
• 清理缓存验证
  路径修改完成后，删除项目下node_modules/.cache目录，重启开发服务，避免构建缓存导致报错残留。

提示：所有前端项目的模块导入路径都需要严格和磁盘文件的命名、层级、大小写保持一致，不要依赖本地文件系统的大小写不敏感特性，否则部署到Linux类服务器时也会出现同类文件找不到的问题。

内容的提问来源于stack exchange，提问作者Sankalp Sachapara