企业官网建设流程全解析

Create React App 在 Heroku 上 npm run build 因文件路径大小写失败怎么排查

【免费下载链接】create-react-appSet up a modern web app by running one command.项目地址: https://gitcode.com/gh_mirrors/cr/create-react-app

把 Create React App 项目部署到 Heroku 时，构建是在 Heroku 的构建环境中执行npm run build完成的。你可能遇到过这种情况：本地npm run build完全正常，推到 Heroku 之后构建却失败了。Create React App 官方文档把“文件路径大小写不一致”列为这一现象的常见原因，因为 Heroku 运行在 Linux 上，而 Linux 是区分大小写的文件系统。本文按官方文档给出的两种报错签名，说明如何判断是不是大小写问题、以及对应的修改方式。

先确认是“本地能构建、Heroku 构建失败”

判断是否进入本文排查范围，看两点：

• 本地跑npm run build能成功生成build目录；
• 同一个项目部署到 Heroku 时，构建这一步失败。

官方 Troubleshooting 文档里专门有一节npm run build fails on Heroku，直接指出：

This may be a problem with case sensitive filenames.

也就是“这可能是文件名大小写敏感导致的问题”，并指向 Deployment 文档的 Resolving Heroku Deployment Errors 一节。原因很明确：Heroku 用的是 Linux，MyDirectory和mydirectory在它眼里是两个不同的目录，所以本地能构建的项目，在 Heroku 上会因为大小写差异让import语句解析不到文件。

部署本身通常使用 Heroku 的 Create React App Buildpack。下面两种报错就是文档列出的最常见情形，先看日志里的错误文本属于哪一种。

修复 “Module not found: Error: Cannot resolve 'file' or 'directory'”

当构建日志里出现类似下面的内容（以下为文档示例，路径以实际项目为准）：

remote: Failed to create a production build. Reason: remote: Module not found: Error: Cannot resolve 'file' or 'directory' MyDirectory in /tmp/build_1234/src

含义是某个import引用的文件或目录，其大小写与磁盘上（或 GitHub 上）实际的名称对不上。文档给出的修复动作是：

• 找到报错里指出的那个文件或目录（例子里是MyDirectory）；
• 检查代码里import它时写的大小写；
• 让 import 路径的大小写与文件系统或 GitHub 上的真实名称完全一致。

关键点在于：本地 OS 对大小写不敏感，所以即使import写成了mydirectory，本地也能跑通；而 Heroku 的 Linux 会把两者当成不同目录，于是构建失败。改完 import 的大小写后重新部署，这一步的报错应当消失。

修复 “Could not find a required file.”

另一种签名是构建日志里出现类似这样的内容（以下为文档示例）：

remote: Could not find a required file. remote: Name: `index.html` remote: Searched in: /tmp/build_a2875fc163b209225122d68916f1d4df/public remote: remote: npm ERR! Linux 3.13.0-105-generic remote: npm ERR! argv "..." "run" "build"

这表示 Heroku 构建包找不到一个必需的文件（例子里是在public目录里找index.html）。文档给出两个要检查的点：

1. 确认文件确实存在，且大小写正确——文件名与代码或构建流程引用的一致；
2. 确认文件没有被.gitignore或~/.gitignore_global忽略。

第二点容易被忽略：如果这个必需的文件被 Git 忽略，它就不会被打进部署包，Heroku 构建时自然找不到。因此要同时检查项目里的.gitignore和全局的~/.gitignore_global，确保像index.html这样的文件没有被排除。

如何判断已经修好

两类问题修完后，重新触发一次 Heroku 部署。成功标志就是构建这一步不再报出上面两种错误文本（Module not found: Error: Cannot resolve 'file' or 'directory'或Could not find a required file.），即之前因大小写或文件缺失而失败的那一步通过。

需要说明的边界：本文只覆盖“因文件路径大小写 / 文件缺失”导致的 Heroku 构建失败。如果 Heroku 构建日志里出现的是别的错误（例如内存不足导致的npm run build提前退出），那是另一类问题，不属于这里的排查范围，应回到 Troubleshooting 文档 对应的小节单独处理。

【免费下载链接】create-react-appSet up a modern web app by running one command.项目地址: https://gitcode.com/gh_mirrors/cr/create-react-app