fix: resolve React 19 and Next.js 16 HMR compatibility issue

2026-03-13 12:13:43 +08:00
parent 4d957eb840
commit b026d2b2ab
3 changed files with 223 additions and 1 deletions
@@ -0,0 +1,156 @@
+# Next.js HMR错误解决方案
+
+## 问题描述
+
+```
+Module [project]/novalon-website/node_modules/next/dist/compiled/react/jsx-dev-runtime.js [app-client] (ecmascript) was instantiated because it was required from module [project]/novalon-website/src/app/(marketing)/contact/page.tsx [app-client] (ecmascript), but module factory is not available. It might have been deleted in an HMR update.
+```
+
+## 原因分析
+
+这是React 19和Next.js 16之间的兼容性问题，特别是在开发模式下的热模块替换（HMR）过程中。
+
+## 解决方案
+
+### 方案1：禁用实验性功能（推荐）
+
+修改 `next.config.ts`，禁用可能导致问题的实验性功能：
+
+```typescript
+experimental: {
+  optimizePackageImports: ['lucide-react', 'framer-motion', '@radix-ui/react-dialog', '@radix-ui/react-dropdown-menu'],
+  // 暂时禁用optimizeCss
+  // optimizeCss: true,
+},
+```
+
+### 方案2：使用生产模式启动
+
+如果HMR问题严重影响开发，可以使用生产模式启动：
+
+```bash
+npm run build
+npm run start
+```
+
+### 方案3：降级React版本（不推荐）
+
+将React降级到18.x版本：
+
+```bash
+npm install react@^18.3.0 react-dom@^18.3.0
+```
+
+### 方案4：升级Next.js版本（推荐）
+
+升级到Next.js 15，它对React 19有更好的支持：
+
+```bash
+npm install next@^15.0.0
+```
+
+### 方案5：使用Turbopack替代
+
+在 `next.config.ts` 中添加：
+
+```typescript
+experimental: {
+  turbo: {
+    rules: {
+      '*.svg': {
+        loaders: ['@svgr/webpack'],
+        as: '*.js',
+      },
+    },
+  },
+},
+```
+
+## 临时解决方案
+
+### 快速修复脚本
+
+运行以下命令清除缓存并重启：
+
+```bash
+# 停止开发服务器
+lsof -ti:3000 | xargs kill -9 2>/dev/null
+
+# 清除缓存
+rm -rf .next node_modules/.cache
+
+# 重新启动
+npm run dev
+```
+
+### 使用修复脚本
+
+```bash
+chmod +x scripts/fix-dev-server.sh
+./scripts/fix-dev-server.sh
+```
+
+### 深度清理
+
+```bash
+./scripts/fix-dev-server.sh --deep
+```
+
+## 长期解决方案
+
+### 1. 等待Next.js更新
+
+Next.js团队正在修复React 19的兼容性问题，建议关注Next.js的更新。
+
+### 2. 使用稳定版本
+
+考虑使用更稳定的React和Next.js版本组合：
+- React 18.x + Next.js 14.x
+- React 19.x + Next.js 15.x+
+
+### 3. 禁用HMR（不推荐）
+
+在 `next.config.ts` 中添加：
+
+```typescript
+webpack: (config, { dev, isServer }) => {
+  if (dev && !isServer) {
+    config.watchOptions = {
+      ignored: /node_modules/,
+    };
+  }
+  return config;
+},
+```
+
+## 推荐行动
+
+### 短期（立即）
+1. ✅ 运行修复脚本清除缓存
+2. ✅ 禁用 `optimizeCss` 实验性功能
+3. ✅ 如果问题持续，使用生产模式开发
+
+### 中期（1-2周）
+1. 考虑升级到Next.js 15
+2. 或降级到React 18
+3. 监控Next.js的React 19支持更新
+
+### 长期（1个月）
+1. 等待Next.js官方修复React 19兼容性
+2. 评估是否需要调整技术栈
+3. 建立更稳定的开发环境
+
+## 监控和反馈
+
+如果问题持续，请：
+
+1. 记录错误发生的频率和场景
+2. 检查是否有特定的文件或组件触发问题
+3. 在Next.js GitHub提交issue
+4. 关注Next.js的更新日志
+
+## 相关资源
+
+- [Next.js React 19支持](https://nextjs.org/docs/app/building-your-application/upgrading)
+- [React 19发布说明](https://react.dev/blog/2024/12/05/react-19)
+- [Next.js已知问题](https://github.com/vercel/next.js/issues)