Create React App部署Vercel时无法解析./index.css编译失败

问题描述 #

将React应用部署到Vercel平台时编译失败，构建环境无法解析./index.css文件，完整构建日志核心报错如下：

[12:22:08.385] Cloning completed: 1.218s
[12:22:08.459] Installing build runtime...
[12:22:10.412] Build runtime installed: 1.953s
[12:22:10.773] No Build Cache available
[12:22:10.926] Installing dependencies...
[12:22:20.413] npm WARN deprecated source-map-url@0.4.1: See https://github.com/lydell/source-map-url#deprecated
[12:22:20.902] npm WARN deprecated source-map-resolve@0.6.0: See https://github.com/lydell/source-map-resolve#deprecated
[12:22:24.009] npm WARN deprecated formidable@1.2.6: Please upgrade to latest, formidable@v2 or formidable@v3! Check these notes:
[12:22:26.196] npm WARN deprecated superagent@5.3.1: Please upgrade to v7.0.2+ of superagent.  We have fixed numerous issues with streams, form-data, attach(), filesystem errors not bubbling up (ENOENT on attach()), and all tests are now passing.  See the releases tab for more information at <https://github.com/visionmedia/superagent/releases>.
[12:22:26.972] npm WARN deprecated svgo@1.3.2: This SVGO version is no longer supported. Upgrade to v2.x.x.
[12:22:34.604] 
[12:22:34.604] added 1420 packages in 23s
[12:22:34.605] 
[12:22:34.605] 170 packages are looking for funding
[12:22:34.605]   run `npm fund` for details
[12:22:34.830] Detected `package-lock.json` generated by npm 7...
[12:22:34.830] Running "npm run build"
[12:22:35.098] 
[12:22:35.098] > collage@0.1.0 build
[12:22:35.099] > react-scripts build
[12:22:35.099] 
[12:22:36.313] Creating an optimized production build...
[12:22:37.029] Failed to compile.
[12:22:37.030] 
[12:22:37.030] Module not found: Error: Can't resolve './index.css' in '/vercel/path0/src'
[12:22:37.030] 
[12:22:37.030] 
[12:22:37.046] Error: Command "npm run build" exited with 1

日志中所有npm WARN deprecated类提示均为依赖版本过时警告，和本次编译失败无关联，无需优先处理。

修复步骤 #

按优先级从高到低排查即可：

• 核对src目录下文件存在性与命名
  进入本地项目的src文件夹，确认是否存在index.css文件：
  • 若文件被误删，直接在src目录新建名为index.css的空文件即可
  • 若文件存在但命名/大小写不匹配（比如命名为Index.css、index.CSS、indx.css），统一修改为全小写的index.css。本地Windows、macOS系统默认文件系统大小写不敏感，本地开发不会触发报错，但Vercel使用Linux构建环境，对文件名大小写校验严格，很容易出现本地正常线上报错的问题
• 核对文件引入语句
  打开引入css的入口文件（通常为src/index.js/src/main.jsx），确认引入语句写为import './index.css'，不要出现路径层级错误、拼写错误、大小写错误
• 核对.gitignore规则
  打开项目根目录的.gitignore文件，确认不存在*.css、src/index.css这类会把css文件排除在git提交外的规则。如果存在对应规则，删除后将本地index.css文件提交推送到远程仓库即可
• 本地验证后重新部署
  本地项目根目录执行npm run build，确认本地构建无报错后，推送代码到关联Vercel的Git分支，平台会自动触发重新部署，即可解决问题。

内容的提问来源于stack exchange，提问作者Patrick Dayton