张翔
38be4a19ef
- 新增 hooks/components/lib 共 9 个测试文件，覆盖边界条件与异常路径 - 补充 animations.test.tsx 用例（RotatingBorder、CounterWithEffect 等） - 修复 useCountUp 结束时 toFixed 精度问题 - 调整 jest 覆盖率配置为渐进式阈值，收缩收集范围 - 新增 docs/lessons-learned.md（经验教训汇总）与 docs/troubleshooting.md（问题排查索引） - 更新 README.md 文档索引
6.5 KiB
6.5 KiB
Troubleshooting（问题排查指南）
常见问题快速索引。按类别组织，每个问题指向详细的解决方案文档。
快速查找
| 症状 | 可能原因 | 解决方案 |
|---|---|---|
| 开发服务器 HMR 报错 | React 19 + Next.js 16 兼容性 | HMR 错误解决 |
| 构建后静态资源 404 | webpackBuildWorker 启用 |
禁用 webpackBuildWorker |
| 页面白屏 | 外部字体加载失败 | 使用本地字体 |
| 大并发下服务崩溃 | 单实例无负载均衡 | 高并发性能优化 |
| Google Analytics 不生效 | 未配置 GA4 ID | GA4 配置 |
| Sentry 错误上报失败 | 未配置 DSN | 监控配置 |
| 测试覆盖率不达标 | 工具函数/hooks 未覆盖 | 测试覆盖率改进计划 |
| E2E 测试视觉回归失败 | 快照过期 | 更新快照 |
| 单元测试 Jest 报错 | 配置/路径别名问题 | 测试配置 |
目录
1. 开发环境
1.1 HMR 模块加载失败
错误信息：
Module factory is not available. It might have been deleted in an HMR update.
原因：React 19 与 Next.js 16 的 HMR 模块缓存机制不兼容。
解决方案：
- 清除缓存：
rm -rf .next node_modules/.cache && npm run dev - 禁用
optimizeCss实验性功能 - 使用修复脚本：
./scripts/fix-dev-server.sh - 深度清理：
./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 配置模板：
2.3 CDN 配置问题
症状：CDN 域名下资源加载失败或缓存未生效。
3. 运行时
3.1 页面白屏
症状：页面加载后空白，控制台无报错或字体加载失败报错。
原因：
- 外部字体服务（Google Fonts）网络加载失败
- JavaScript 运行时错误
检查步骤：
- 打开浏览器开发者工具 → Network 面板 → 检查字体文件是否加载成功
- 检查 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 报错。
常见原因：
- 路径别名未解析（
@/映射问题） - 测试文件引用了被删除/移动的模块
- 覆盖率门槛未达到
检查步骤：
- 确认
jest.config.js中moduleNameMapper正确配置 - 运行
npx jest --testPathPattern="your-test"单独调试 - 运行
npx jest --no-coverage跳过覆盖率检查
4.2 E2E 测试失败
症状：npm run test 或 npx playwright test 报错。
常见原因：
- 开发服务器未运行或端口不匹配
- 选择器（locator）不匹配当前 DOM 结构
- 视觉回归快照过期
解决方案：
- 运行
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 数据面板无数据或实时报告为空。
检查步骤：
- 确认
.env.production中NEXT_PUBLIC_GA_ID已配置 - 检查浏览器 Network 面板是否有
analytics.google.com请求 - 确认未开启 ad blocker
详细文档：GA4 设置
5.2 Sentry 错误上报失败
症状：Sentry 面板无错误数据。
检查步骤：
- 确认
.env.production中SENTRY_DSN已配置 - 检查
src/lib/sentry.ts初始化代码 - 确认 Sentry 项目 DSN 与代码一致
详细文档：Sentry 设置 | Lighthouse CI 指南
参考文档索引
| 文档 | 内容 |
|---|---|
| HMR 错误解决 | HMR 模块加载失败的所有解决方案 |
| 高并发性能优化 | 性能瓶颈分析和优化方案 |
| CDN 配置 | CDN 部署和缓存配置 |
| 监控配置 | Sentry + UptimeRobot + GA4 配置 |
| 部署文档 | 完整部署流程和 Nginx 配置 |
| 回滚流程 | 生产环境回滚操作步骤 |
| 测试覆盖率改进计划 | 测试覆盖率提升策略 |
| 分层测试优化指南 | 测试分层和执行效率优化 |
| 视觉测试标准 | 视觉回归测试规范 |
更新记录
| 日期 | 更新内容 |
|---|---|
| 2026-07-07 | 初始创建，整合现有分散的故障排查文档 |