create-react-app 排障指南：npm start / test / build 常见问题的官方解决方案与源码级原理

本文基于 create-react-app 官方文档中的排障页面整理，覆盖 npm start 不检测文件变更、Linux 下 watch 报 ENOSPC 错误、macOS 上 npm test 挂起、npm run build 提前退出或无法压缩（minify）、Moment.js 语言包缺失等高频故障。文中每个故障都给出可直接执行的修复命令，并结合同仓库中 react-scripts 的源码（如构建入口脚本、webpack 配置）解释报错信息的真实来源，适用于当前仓库对应的 react-scripts@5.1.0 及其维护的 CRA 项目。

为什么需要一份排障清单

CRA 的项目骨架是零配置的：npm start、npm test、npm run build 背后的 webpack、Jest、Babel 配置都封装在 react-scripts 包里。这带来便利的副作用是——当开发服务器、测试运行器或构建进程行为异常时，你往往看不到配置本身，只能从错误信息和环境特征入手排查。官方排障文档的价值正在于此：它按"症状 → 环境特征 → 修复动作"组织，且大多能追溯到 react-scripts 的具体实现。

npm start 不检测文件变更

正常情况下，npm start 运行期间保存文件，浏览器应自动刷新为新代码。如果热更新失效，按以下清单逐项排查（官方排障文档给出的完整 workaround 列表）：

1. 确认文件被入口文件引用：TypeScript 语言服务器会对任意源文件报错，但 webpack 只会重新加载被入口点直接或间接 import 的文件。一个从未被引入的模块保存后不会触发重建。
2. 项目放在 Dropbox 同步目录：把项目移出 Dropbox 文件夹。文件同步工具会在写入时替换文件句柄，破坏 watcher 的监听。
3. 通过目录名引用 index.js 时 watcher 看不到该文件：这是一个已知的 webpack bug，需要重启 watcher 进程。
4. 编辑器"安全写入"（safe write）：Vim、IntelliJ 等编辑器的 safe write 会"写临时文件 → 重命名覆盖"，而非原地修改，watcher 会把这识别成旧文件被删除、新文件出现，从而丢失监听。需要在编辑器中关闭该选项。
5. 项目路径包含括号：将项目移到不含 (、) 的路径下。这是 watchpack 的已知问题。
6. Linux / macOS 上系统 watcher 数量不足：见下文"watch 报 ENOSPC"一节。
7. 虚拟机环境（如 Vagrant + VirtualBox）：虚拟机的共享目录不向 guest 传递宿主机的文件系统事件，内核级 inotify 失效。官方给出的解法是在项目根目录创建 .env 文件（若不存在），写入：

CHOKIDAR_USEPOLLING=true

这样下次 npm start 时，webpack 底层的 chokidar 监听器会切换到轮询模式（polling），以定时比对文件状态代替内核事件。该环境变量在官方配置文档的环境变量表中也被标注为仅 react-scripts start 使用（见 advanced-configuration.md）。

以上均无效时，官方建议到对应 issue 线程中反馈，而不是盲目改配置。

npm start 因 watch 报错而失败：ENOSPC

在 Linux 上若看到类似 ENOSPC: System limit for number of file watchers reached 的错误，说明系统的 inotify 监听上限被 node_modules 里成千上万个文件耗尽。修复方式是调大 fs.inotify.max_user_watches 内核参数。

Debian、RedHat 等发行版，执行：

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

Arch Linux，执行：

echo fs.inotify.max_user_watches=524288 | sudo tee /etc/sysctl.d/40-max-user-watches.conf && sudo sysctl --system

两条命令的区别只是持久化位置：前者追加进 /etc/sysctl.conf 后用 sysctl -p 重载；后者写入 /etc/sysctl.d/ 的独立 conf 文件后用 sysctl --system 全量应用。修改后无需重启系统，重新运行 npm start 即可生效。

npm test 在 macOS Sierra 上挂起或崩溃

如果 npm test 在打印出 react-scripts test 之后控制台就卡住，问题通常出在 Jest 依赖的 Watchman（Facebook 的文件监听守护进程）安装上。官方推荐的排查顺序：

1. 先删掉 node_modules 重新安装：执行 npm install（或 yarn）。
2. 升级 Watchman 到 4.7.0 或更新版本：有报告称该版本修复了此问题。使用 Homebrew 时执行：

watchman shutdown-server
brew update
brew reinstall watchman

3. 仍未解决，尝试卸载 Watchman 的 LaunchAgent 注册：

launchctl unload -F ~/Library/LaunchAgents/com.github.facebook.watchman.plist

4. 最后手段：有报告称直接卸载 Watchman 也能解决问题（Jest 会回退到非 Watchman 的文件发现方式，代价是测试目录很大时启动变慢）。

该问题在 Jest、Watchman、ember-cli 社区均有大量记录，本质是旧版 Watchman 二进制与 macOS 文件系统的兼容性问题，与项目代码无关。

npm run build 提前退出：内存不足

在内存受限且没有交换空间（swap）的机器上（云主机很常见），即使很小的项目，构建也可能让内存占用上升数百 MB。可用内存低于 1 GB 时，构建进程会被操作系统以 SIGKILL 杀掉，此时你会看到如下提示：

The build failed because the process exited too early. This probably means the system ran out of memory or someone called kill -9 on the process.

这条提示并非来自 webpack 本身，而是 react-scripts 的 CLI 入口主动打印的。在 packages/react-scripts/bin/react-scripts.js 中可以看到：build、eject、start、test 四个脚本都以 spawn.sync 子进程方式运行，父进程检查返回的 result.signal——收到 SIGKILL 时打印"可能内存不足或被 kill -9"，收到 SIGTERM 时则提示"可能被人 kill/killall，或系统正在关机"，随后 process.exit(1)。

也就是说，这条报错是信号驱动的兜底诊断：构建进程没有正常退出码，而是被信号强杀。官方给出的解法有二：

• 给构建机器增加 swap 空间，或
• 在本地机器上构建，而不是在受限的云端容器里跑。

npm run build 在 Heroku 上失败：文件名大小写问题

Linux（Heroku 运行所用系统）的文件系统是大小写敏感的，而 macOS、Windows 默认大小写不敏感。如果你的项目里存在 import './MyComponent' 而实际文件是 myComponent.js，本地构建能通过，部署到 Heroku 后 import 解析就会失败。官方排障文档将此问题指向部署文档中的 "Resolving Heroku Deployment Errors" 一节（见 deployment.md），核心做法是在本地复现 Linux 的行为：

1. 确认导入路径与文件名的逐字符大小写完全一致；
2. 可用大小写敏感文件系统（如 Linux、CI 环境）跑一次 npm run build 来暴露问题。

Moment.js 语言包缺失：默认只有英语

如果你使用 Moment.js，会注意到构建产物中默认只有英文 locale。这不是 bug，而是 react-scripts 在 webpack 配置里刻意注入的优化：locale 文件体积很大，绝大多数项目只需要其中一两个语言。

在 packages/react-scripts/config/webpack.config.js 中可以看到实现：

// Moment.js is an extremely popular library that bundles large locale files
// by default due to how webpack interprets its code. This is a practical
// solution that requires the user to opt into importing specific locales.
new webpack.IgnorePlugin({
  resourceRegExp: /^\.\/locale$/,
  contextRegExp: /moment$/,
}),

webpack.IgnorePlugin 让 webpack 忽略 moment 包内 ./locale/ 目录下的所有模块——除非你显式 import。要加入某个语言包，显式引入即可：

import moment from 'moment';
import 'moment/locale/fr';

如果导入了多个语言包，可以用 moment.locale() 在运行时切换，但只能切换到已被显式导入过的语言：

import moment from 'moment';
import 'moment/locale/fr';
import 'moment/locale/es';

// ...

moment.locale('fr');

源码注释也说明：如果你的项目不用 Moment.js，可以（在 eject 之后）直接移除这个插件，以消除对该优化路径的依赖。

npm run build 压缩（minify）失败

在 react-scripts@2.0.0 之前，构建失败于压缩阶段的常见原因是第三方 node_modules 使用了压缩器无法处理的现代 JavaScript 语法。从 react-scripts@2.0.0 起，Babel 会对 node_modules 中的标准现代语法做编译，该问题已被解决。

因此如果你今天仍看到 minify 相关报错，几乎可以断定是在使用旧版本 react-scripts。两条出路：

• 升级依赖，避开使用现代语法的包；或
• 将 react-scripts 升级到 >=2.0.0（当前仓库维护的版本为 5.1.0，见 packages/react-scripts/package.json），并遵循对应 changelog 的迁移说明（版本升级路径可参考 updating-to-new-releases.md）。

排障速查表

症状	常见根因	修复动作
npm start 保存后浏览器不刷新	文件未被入口引用 / Dropbox 同步 / 路径含括号 / 编辑器 safe write / 虚拟机	对应移出、改路径、关 safe write；VM 中设置 CHOKIDAR_USEPOLLING=true
ENOSPC: System limit for number of file watchers reached	内核 inotify 上限不足	调大 fs.inotify.max_user_watches（Debian 系与 Arch 命令见上文）
npm test 打印 banner 后卡死（macOS）	Watchman 安装/版本问题	重装 node_modules → 升级 Watchman ≥4.7.0 → 卸载 LaunchAgent → 最后卸载 Watchman
构建提示 "exited too early"	进程被 SIGKILL（多为 OOM）	增加 swap，或换到内存充足的机器本地构建
Heroku 构建失败、本地正常	大小写敏感文件系统	修正 import 与文件名的逐字符大小写
Moment.js 只有英语 locale	webpack.IgnorePlugin 刻意忽略 moment/locale	显式 import 'moment/locale/xx'
minify 失败	react-scripts < 2.0.0	升级 react-scripts 至 >=2.0.0

小结

这份排障文档覆盖了 CRA 日常开发中最高频的四类环境故障：文件监听（watcher 失效与内核上限）、测试运行器（Watchman 兼容性）、构建资源（内存 OOM）与构建配置（locale 优化、minify 版本问题）。其价值在于每一类故障都给出了可复制的命令，且多数症状能在 react-scripts 源码中找到对应实现——例如 "exited too early" 来自 bin/react-scripts.js 的信号检查，Moment locale 优化来自 webpack.config.js 的 IgnorePlugin。当你遇到本文未覆盖的报错时，建议先定位它属于"环境限制"还是"配置行为"，再对照相应章节缩小范围。