diff --git a/docs/HMR-ERROR-SOLUTIONS.md b/docs/HMR-ERROR-SOLUTIONS.md new file mode 100644 index 0000000..bb3666c --- /dev/null +++ b/docs/HMR-ERROR-SOLUTIONS.md @@ -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) \ No newline at end of file diff --git a/next.config.ts b/next.config.ts index eeaf1dc..f78d25c 100644 --- a/next.config.ts +++ b/next.config.ts @@ -26,7 +26,8 @@ const nextConfig: NextConfig = { reactProductionProfiling: !isDev, experimental: { optimizePackageImports: ['lucide-react', 'framer-motion', '@radix-ui/react-dialog', '@radix-ui/react-dropdown-menu'], - optimizeCss: true, + // 暂时禁用optimizeCss以解决React 19和Next.js 16的HMR兼容性问题 + // optimizeCss: true, }, compiler: { removeConsole: process.env.NODE_ENV === 'production', diff --git a/scripts/fix-dev-server.sh b/scripts/fix-dev-server.sh new file mode 100644 index 0000000..cae8147 --- /dev/null +++ b/scripts/fix-dev-server.sh @@ -0,0 +1,65 @@ +#!/bin/bash + +echo "🔧 Next.js 开发服务器问题修复工具" +echo "==================================" +echo "" + +# 颜色定义 +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +RED='\033[0;31m' +NC='\033[0m' # No Color + +# 检查是否有进程在3000端口 +if lsof -ti:3000 > /dev/null 2>&1; then + echo -e "${YELLOW}⚠️ 检测到端口3000上有进程运行${NC}" + echo "正在停止进程..." + lsof -ti:3000 | xargs kill -9 2>/dev/null + echo -e "${GREEN}✅ 进程已停止${NC}" + sleep 2 +else + echo -e "${GREEN}✅ 端口3000未被占用${NC}" +fi + +# 清除缓存 +echo "" +echo "清除Next.js缓存..." + +if [ -d ".next" ]; then + echo "删除 .next 目录..." + rm -rf .next + echo -e "${GREEN}✅ .next 目录已清除${NC}" +else + echo -e "${GREEN}✅ .next 目录不存在,无需清除${NC}" +fi + +# 清除node_modules缓存(可选) +if [ "$1" == "--deep" ]; then + echo "" + echo "执行深度清理..." + + if [ -d "node_modules/.cache" ]; then + echo "删除 node_modules/.cache 目录..." + rm -rf node_modules/.cache + echo -e "${GREEN}✅ node_modules/.cache 已清除${NC}" + fi + + if [ -d ".turbo" ]; then + echo "删除 .turbo 目录..." + rm -rf .turbo + echo -e "${GREEN}✅ .turbo 已清除${NC}" + fi +fi + +echo "" +echo -e "${GREEN}✅ 修复完成!${NC}" +echo "" +echo "现在可以运行开发服务器:" +echo -e "${YELLOW}npm run dev${NC}" +echo "" +echo "或者使用以下命令:" +echo -e "${YELLOW}npm run dev${NC} - 启动开发服务器" +echo -e "${YELLOW}npm run build${NC} - 构建生产版本" +echo "" +echo "提示:如果问题仍然存在,尝试使用 --deep 参数进行深度清理:" +echo -e "${YELLOW}./scripts/fix-dev-server.sh --deep${NC}" \ No newline at end of file