本地Docker环境切换Git分支后create-react-app编译失败原因及调试

• 缓存残留：create-react-app自带的webpack缓存、Docker容器里的node_modules/.cache，或是分支切换后没清理的编译产物（比如build/目录），会让编译时混进新旧代码，触发报错。
• 依赖版本不匹配：不同分支的package.json可能有不同的React或相关依赖版本，切换分支后没在容器里重新装依赖，导致react和react-dom版本不一致，或者重复引入了React实例，直接引发invalid hook call错误。
• 文件同步延迟：Docker和本地主机的文件同步有延迟，分支切换后容器没及时拿到最新源码，热重载时加载了新旧混合的代码。
• HMR状态混乱：热模块重载的缓存状态在分支切换后没重置，新旧模块的依赖关系搅在一起，就会编译失败或者hook调用出错。

快速清理缓存 #

• 进入容器执行启动命令时加清缓存参数：docker exec <service name> npm start -- --no-cache，强制webpack不用缓存编译。
• 手动删除容器里的缓存目录：docker exec <service name> rm -rf node_modules/.cache，这是create-react-app存放webpack缓存的位置。

同步依赖版本 #

• 分支切换后，直接在容器里重新安装依赖：docker exec <service name> npm install。嫌手动麻烦的话，可以整个git钩子，比如在post-checkout钩子中自动执行这步。
• 检查是否存在重复的React实例：docker exec <service name> npm ls react，如果输出显示多个版本，说明依赖冲突，直接删除重装：docker exec <service name> rm -rf node_modules package-lock.json && npm install。

优化文件同步 #

• 检查docker-compose的卷挂载配置，确保源码目录是实时同步的。如果用Docker Desktop，给挂载添加consistency: consistent参数，能提升同步可靠性。
• 分支切换后，手动强制刷新浏览器（Ctrl+Shift+R），或者在容器里重启dev server而非整个容器：先杀掉旧进程docker exec <service name> pkill node，再重新启动docker exec <service name> npm start，这比重启容器快很多。

重置HMR状态 #

• 打开浏览器的React开发者工具，点击右上角齿轮图标，选择"Reload DevTools"，同时清空浏览器缓存（Ctrl+Shift+Delete），避免前端旧缓存干扰。
• 如果用了craco或者react-app-rewired修改配置，可以在webpack配置里添加cache: false，或者在启动脚本里加入清缓存的步骤，让分支切换时自动重置HMR缓存。

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