# 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 | 初始创建，整合现有分散的故障排查文档 |