Docker devcontainer中VSCode React项目热重载/快速刷新失效求助

根因说明 #

react-scripts v5 内部对文件变更的监听是两套独立链路，刚好对应观察到的异常现象：

• 构建配置类文件（package.json、.env 配置文件、自定义webpack配置等）由dev server主进程通过Node原生fs接口监听，变更后直接触发全量服务重启，这部分逻辑不经过chokidar、webpack-dev-server的业务源码监听链路，所以即使业务监听链路故障，这类文件的变更依然能被捕获，触发重编译动作。
• src目录下的业务源码（.js/.jsx/.ts/.tsx等）由webpack-dev-server调用chokidar做增量监听，变更后走Fast Refresh增量更新链路，这部分链路任意环节故障，都会表现为修改.js文件无响应、即使触发重编译页面也不加载更新内容。

可直接落地的修复步骤 #

按优先级依次操作，每步完成后重启npm start验证效果：

• 修正错误的环境变量配置：当前设置的FAST_REFRESH=false是直接关闭快速刷新功能，先将该配置改为true，所有环境变量统一放到项目根目录的.env.local文件中（不要仅在终端临时设置），正确配置参考如下：

FAST_REFRESH=true
CHOKIDAR_USEPOLLING=true
WDS_SOCKET_PORT=0
SKIP_PREFLIGHT_CHECK=true

新增的WDS_SOCKET_PORT=0用于解决CRA v5在WSL/远程开发/端口映射场景下，websocket通信端口不匹配导致重编译完成但页面收不到更新通知的问题，对应“触发重编译但页面不更新”的故障表现。

• 校验目录结构合规性：react-scripts默认仅监听src/目录下的业务文件，如果当前的.js页面文件存放在src目录外（比如根目录自定义pages文件夹、public目录下），会直接被监听链路忽略，必须将所有需要热更新的业务代码迁移到src目录内。
• 修正import路径大小写错误：跨系统（WSL/Windows/macOS）开发场景下，如果import语句的路径大小写和实际文件路径不一致（例如写为import Home from './Pages/Home'但实际文件路径是./pages/home.js），CRA v5的模块缓存机制会直接跳过该文件的变更检测，全局排查所有import语句，保证路径大小写和实际文件完全匹配。
• 清除构建缓存后重启：停止当前运行的dev server，删除项目根目录下node_modules/.cache文件夹，清除CRA的持久化构建缓存后再重新启动服务，避免旧缓存导致的更新不生效问题。

其他排查方向 #

如果上述步骤操作后仍未解决，按以下方向逐一排查：

• 检查VSCode保存配置：打开VSCode设置，搜索files.autoSave，如果设置为afterDelay模式，先改为onFocusChange或手动保存模式，高频次的碎片化自动写入会被chokidar判定为无效变更直接过滤。
• 校验jsconfig/tsconfig配置：如果项目中存在jsconfig.json/tsconfig.json做路径别名配置，检查include字段是否覆盖了所有src下的业务文件，exclude字段是否错误排除了需要监听的业务源码路径。
• 校验Node版本兼容性：react-scripts v5和Node 18早期版本（18.0~18.12）、Node 20早期版本存在已知的文件监听兼容问题，切换到Node 18.20+ LTS或Node 20.10+ LTS版本，重新安装依赖后重试。
• 检查WSL文件路径问题：如果使用WSL环境开发，不要将项目放在Windows挂载盘路径（形如/mnt/c/xxx）下，跨文件系统的事件丢包率极高，将项目迁移到WSL自身的用户目录（形如~/projects/xxx）下可大幅提升监听稳定性。
• 检查全局路径长度限制：Windows系统下如果项目嵌套层级过深，文件路径长度超过系统默认限制，会导致chokidar无法正常监听文件变更，将项目迁移到更浅层的目录（比如直接放到磁盘根目录下的项目文件夹）即可解决。

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