张翔
38be4a19ef
- 新增 hooks/components/lib 共 9 个测试文件，覆盖边界条件与异常路径 - 补充 animations.test.tsx 用例（RotatingBorder、CounterWithEffect 等） - 修复 useCountUp 结束时 toFixed 精度问题 - 调整 jest 覆盖率配置为渐进式阈值，收缩收集范围 - 新增 docs/lessons-learned.md（经验教训汇总）与 docs/troubleshooting.md（问题排查索引） - 更新 README.md 文档索引
200 lines
6.5 KiB
Markdown
200 lines
6.5 KiB
Markdown
# Troubleshooting（问题排查指南）
|
||
|
||
> 常见问题快速索引。按类别组织，每个问题指向详细的解决方案文档。
|
||
|
||
## 快速查找
|
||
|
||
| 症状 | 可能原因 | 解决方案 |
|
||
|------|---------|---------|
|
||
| 开发服务器 HMR 报错 | React 19 + Next.js 16 兼容性 | [HMR 错误解决](./HMR-ERROR-SOLUTIONS.md) |
|
||
| 构建后静态资源 404 | `webpackBuildWorker` 启用 | [禁用 webpackBuildWorker](#11-构建后静态资源-404) |
|
||
| 页面白屏 | 外部字体加载失败 | [使用本地字体](#12-页面白屏---字体加载失败) |
|
||
| 大并发下服务崩溃 | 单实例无负载均衡 | [高并发性能优化](./PERFORMANCE_OPTIMIZATION.md) |
|
||
| Google Analytics 不生效 | 未配置 GA4 ID | [GA4 配置](./GOOGLE_ANALYTICS_SETUP.md) |
|
||
| Sentry 错误上报失败 | 未配置 DSN | [监控配置](./LIGHTWEIGHT_MONITORING.md) |
|
||
| 测试覆盖率不达标 | 工具函数/hooks 未覆盖 | [测试覆盖率改进计划](./test-coverage-improvement-plan.md) |
|
||
| E2E 测试视觉回归失败 | 快照过期 | [更新快照](../CLAUDE.md#common-commands) |
|
||
| 单元测试 Jest 报错 | 配置/路径别名问题 | [测试配置](../config/test/jest.config.js) |
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [1. 开发环境](#1-开发环境)
|
||
- [2. 构建与部署](#2-构建与部署)
|
||
- [3. 运行时](#3-运行时)
|
||
- [4. 测试](#4-测试)
|
||
- [5. 监控与分析](#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 错误解决](./HMR-ERROR-SOLUTIONS.md)
|
||
|
||
---
|
||
|
||
## 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 配置模板：
|
||
|
||
- [部署文档](./deployment/DEPLOYMENT.md)
|
||
- [Phase 1 部署指南](./deployment/phase1-deployment-guide.md)
|
||
- [回滚流程](./deployment/rollback-procedure.md)
|
||
|
||
### 2.3 CDN 配置问题
|
||
|
||
**症状**：CDN 域名下资源加载失败或缓存未生效。
|
||
|
||
**解决方案**：[CDN 配置指南](./CDN_CONFIGURATION.md) | [CDN 快速入门](./CDN_QUICK_START.md)
|
||
|
||
---
|
||
|
||
## 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` 跳过覆盖率检查
|
||
|
||
**详细文档**：[测试配置](../config/test/jest.config.js) | [测试指南](./testing-guide.md)
|
||
|
||
### 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 配置](../e2e/playwright.config.ts)
|
||
|
||
### 4.3 视觉回归测试
|
||
|
||
**症状**：视觉对比测试失败，截图差异过大。
|
||
|
||
**解决方案**：
|
||
- 更新基线快照：`npm run test:visual:update`
|
||
- 查看差异报告：`e2e/visual-snapshots/diff/`
|
||
- 详细标准：[视觉测试标准](./visual-testing-standards.md)
|
||
|
||
---
|
||
|
||
## 5. 监控与分析
|
||
|
||
### 5.1 Google Analytics 不生效
|
||
|
||
**症状**：GA4 数据面板无数据或实时报告为空。
|
||
|
||
**检查步骤**：
|
||
1. 确认 `.env.production` 中 `NEXT_PUBLIC_GA_ID` 已配置
|
||
2. 检查浏览器 Network 面板是否有 `analytics.google.com` 请求
|
||
3. 确认未开启 ad blocker
|
||
|
||
**详细文档**：[GA4 设置](./GOOGLE_ANALYTICS_SETUP.md)
|
||
|
||
### 5.2 Sentry 错误上报失败
|
||
|
||
**症状**：Sentry 面板无错误数据。
|
||
|
||
**检查步骤**：
|
||
1. 确认 `.env.production` 中 `SENTRY_DSN` 已配置
|
||
2. 检查 `src/lib/sentry.ts` 初始化代码
|
||
3. 确认 Sentry 项目 DSN 与代码一致
|
||
|
||
**详细文档**：[Sentry 设置](./sentry-setup-guide.md) | [Lighthouse CI 指南](./lighthouse-ci-guide.md)
|
||
|
||
---
|
||
|
||
## 参考文档索引
|
||
|
||
| 文档 | 内容 |
|
||
|------|------|
|
||
| [HMR 错误解决](./HMR-ERROR-SOLUTIONS.md) | HMR 模块加载失败的所有解决方案 |
|
||
| [高并发性能优化](./PERFORMANCE_OPTIMIZATION.md) | 性能瓶颈分析和优化方案 |
|
||
| [CDN 配置](./CDN_CONFIGURATION.md) | CDN 部署和缓存配置 |
|
||
| [监控配置](./LIGHTWEIGHT_MONITORING.md) | Sentry + UptimeRobot + GA4 配置 |
|
||
| [部署文档](./deployment/DEPLOYMENT.md) | 完整部署流程和 Nginx 配置 |
|
||
| [回滚流程](./deployment/rollback-procedure.md) | 生产环境回滚操作步骤 |
|
||
| [测试覆盖率改进计划](./test-coverage-improvement-plan.md) | 测试覆盖率提升策略 |
|
||
| [分层测试优化指南](./test-optimization-guide.md) | 测试分层和执行效率优化 |
|
||
| [视觉测试标准](./visual-testing-standards.md) | 视觉回归测试规范 |
|
||
|
||
---
|
||
|
||
## 更新记录
|
||
|
||
| 日期 | 更新内容 |
|
||
|------|---------|
|
||
| 2026-07-07 | 初始创建，整合现有分散的故障排查文档 | |