novalon-website/docs/troubleshooting.md

Troubleshooting（问题排查指南）

常见问题快速索引。按类别组织，每个问题指向详细的解决方案文档。

快速查找

症状	可能原因	解决方案
开发服务器 HMR 报错	React 19 + Next.js 16 兼容性	HMR 错误解决
构建后静态资源 404	webpackBuildWorker 启用	禁用 webpackBuildWorker
页面白屏	外部字体加载失败	使用本地字体
大并发下服务崩溃	单实例无负载均衡	高并发性能优化
Google Analytics 不生效	未配置 GA4 ID	GA4 配置
Sentry 错误上报失败	未配置 DSN	监控配置
测试覆盖率不达标	工具函数/hooks 未覆盖	测试覆盖率改进计划
E2E 测试视觉回归失败	快照过期	更新快照
单元测试 Jest 报错	配置/路径别名问题	测试配置

---

目录

• 1. 开发环境
• 2. 构建与部署
• 3. 运行时
• 4. 测试
• 5. 监控与分析

---

1. 开发环境

1.1 HMR 模块加载失败

错误信息：

Module factory is not available. It might have been deleted in an HMR update.

原因：React 19 与 Next.js 16 的 HMR 模块缓存机制不兼容。

解决方案：

1. 清除缓存：rm -rf .next node_modules/.cache && npm run dev
2. 禁用 optimizeCss 实验性功能
3. 使用修复脚本：./scripts/fix-dev-server.sh
4. 深度清理：./scripts/fix-dev-server.sh --deep

详细文档：HMR 错误解决

---

2. 构建与部署

2.1 构建后静态资源 404

症状：部署后 _next/static/ 路径下的 JS/CSS 文件返回 404。

原因：next.config.ts 中启用了 experimental.webpackBuildWorker: true。

解决方案：确保 next.config.ts 中该配置为 false 或未启用。

2.2 Nginx 反向代理配置

症状：子域名（product.novalon.cn 等）访问报错或路由失败。

解决方案：参考部署文档中的 Nginx 配置模板：

• 部署文档
• Phase 1 部署指南
• 回滚流程

2.3 CDN 配置问题

症状：CDN 域名下资源加载失败或缓存未生效。

解决方案：CDN 配置指南 | CDN 快速入门

---

3. 运行时

3.1 页面白屏

症状：页面加载后空白，控制台无报错或字体加载失败报错。

原因：

1. 外部字体服务（Google Fonts）网络加载失败
2. JavaScript 运行时错误

检查步骤：

1. 打开浏览器开发者工具 → Network 面板 → 检查字体文件是否加载成功
2. 检查 Console 面板是否有 JS 错误

解决方案：

• 确保所有字体使用本地文件（src/app/fonts/）
• 检查 layout.tsx 中字体引用路径是否正确

3.2 图片加载失败

症状：页面图片显示为 broken image 图标。

原因：next/image 在静态导出模式下需要 unoptimized 配置。

解决方案：

• 在 next.config.ts 中设置 images.unoptimized: true
• 或改用 <img> 标签替代 next/image

---

4. 测试

4.1 单元测试失败

症状：npm run test:unit 或 npx jest 报错。

常见原因：

1. 路径别名未解析（@/ 映射问题）
2. 测试文件引用了被删除/移动的模块
3. 覆盖率门槛未达到

检查步骤：

1. 确认 jest.config.js 中 moduleNameMapper 正确配置
2. 运行 npx jest --testPathPattern="your-test" 单独调试
3. 运行 npx jest --no-coverage 跳过覆盖率检查

详细文档：测试配置 | 测试指南

4.2 E2E 测试失败

症状：npm run test 或 npx playwright test 报错。

常见原因：

1. 开发服务器未运行或端口不匹配
2. 选择器（locator）不匹配当前 DOM 结构
3. 视觉回归快照过期

解决方案：

• 运行 npm run test:visual:update 更新视觉快照
• 按标签筛选：npx playwright test --grep "@smoke"

详细文档：Playwright 配置

4.3 视觉回归测试

症状：视觉对比测试失败，截图差异过大。

解决方案：

• 更新基线快照：npm run test:visual:update
• 查看差异报告：e2e/visual-snapshots/diff/
• 详细标准：视觉测试标准

---

5. 监控与分析

5.1 Google Analytics 不生效

症状：GA4 数据面板无数据或实时报告为空。

检查步骤：

1. 确认 .env.production 中 NEXT_PUBLIC_GA_ID 已配置
2. 检查浏览器 Network 面板是否有 analytics.google.com 请求
3. 确认未开启 ad blocker

详细文档：GA4 设置

5.2 Sentry 错误上报失败

症状：Sentry 面板无错误数据。

检查步骤：

1. 确认 .env.production 中 SENTRY_DSN 已配置
2. 检查 src/lib/sentry.ts 初始化代码
3. 确认 Sentry 项目 DSN 与代码一致

详细文档：Sentry 设置 | Lighthouse CI 指南

---

参考文档索引

文档	内容
HMR 错误解决	HMR 模块加载失败的所有解决方案
高并发性能优化	性能瓶颈分析和优化方案
CDN 配置	CDN 部署和缓存配置
监控配置	Sentry + UptimeRobot + GA4 配置
部署文档	完整部署流程和 Nginx 配置
回滚流程	生产环境回滚操作步骤
测试覆盖率改进计划	测试覆盖率提升策略
分层测试优化指南	测试分层和执行效率优化
视觉测试标准	视觉回归测试规范

---

更新记录

日期	更新内容
2026-07-07	初始创建，整合现有分散的故障排查文档