# 开发环境构建性能测量

## 📋 概述

为了分析和优化开发环境的构建速度，我们在 `config/dev.ts` 中集成了 `BuildTimerPlugin`，用于测量：
- 首次编译时间
- 增量编译时间（修改代码后的重新编译）
- 编译的模块数量
- 编译错误和警告

## 🚀 使用方法

### 启动开发服务器

```bash
npm run dev:h5
```

### 预期输出

#### 首次编译

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔨 [构建 #1] 首次编译开始... 22:15:30
✅ [构建 #1] 编译完成！ 22:16:15
⏱️  耗时: 45.23s (45230ms)
📊 模块数: 1234
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

#### 增量编译（修改代码后）

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔨 [构建 #2] 增量编译开始... 22:16:45
✅ [构建 #2] 编译完成！ 22:16:48
⏱️  耗时: 3.45s (3450ms)
📊 模块数: 1234
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## 📊 建立性能基准

### 步骤 1：记录首次编译时间

1. 清理缓存（可选，确保公平对比）
   ```bash
   npm run clean:cache
   ```

2. 启动开发服务器
   ```bash
   npm run dev:h5
   ```

3. 记录 **首次编译** 的时间
   - 示例：`⏱️  耗时: 45.23s (45230ms)`

### 步骤 2：记录增量编译时间

1. 修改一个文件（如 `src/app.tsx`），添加一个空格或注释
2. 保存文件
3. 等待自动重新编译
4. 记录 **增量编译** 的时间
   - 示例：`⏱️  耗时: 3.45s (3450ms)`

### 步骤 3：多次测试取平均值

为了获得更准确的数据，建议：
- 首次编译：测试 3 次，取平均值
- 增量编译：修改不同文件测试 5-10 次，取平均值

## 📝 性能基准记录模板

```
项目：zsis
测试日期：2025-12-28
测试环境：
- 操作系统：Windows 11
- CPU：[记录你的 CPU]
- 内存：[记录你的内存]
- Node 版本：[运行 node -v]
- npm 版本：[运行 npm -v]

优化前基准：
┌─────────────┬──────────────┬────────────┐
│   编译类型   │   平均耗时   │   模块数   │
├─────────────┼──────────────┼────────────┤
│ 首次编译     │   ____ s     │    ____    │
│ 增量编译     │   ____ s     │    ____    │
└─────────────┴──────────────┴────────────┘

优化后对比：
（在实施优化后填写）
┌─────────────┬──────────────┬────────────┬──────────┐
│   编译类型   │   平均耗时   │   模块数   │  提升幅度 │
├─────────────┼──────────────┼────────────┼──────────┤
│ 首次编译     │   ____ s     │    ____    │   __%    │
│ 增量编译     │   ____ s     │    ____    │   __%    │
└─────────────┴──────────────┴────────────┴──────────┘
```

## 🔍 性能分析指标

### 正常范围参考

基于 Taro + Webpack 5 项目的一般经验：

| 编译类型 | 小型项目 | 中型项目 | 大型项目 |
|---------|---------|---------|---------|
| 首次编译 | 10-20s | 20-40s | 40-90s |
| 增量编译 | 1-3s | 2-5s | 3-8s |

你的项目属于**大型项目**（医学影像系统，包含 Cornerstone.js 等大型库）。

### 性能瓶颈判断

如果你的构建时间超过以下阈值，说明存在性能问题：

- 首次编译 > 60s
- 增量编译 > 10s
- 增量编译时模块数量过多（说明缓存可能没有生效）

## 🚀 下一步优化建议

一旦建立了性能基准，可以按以下顺序进行优化：

### 优化 1：修改 Source Map 类型（预计提升 40-60%）

```typescript
// config/dev.ts
sourceMapType: 'cheap-module-source-map',  // 改为这个
```

### 优化 2：开发环境跳过 node_modules 编译（预计提升 20-30%）

只在生产环境强制编译 node_modules 中的包。

### 优化 3：启用 thread-loader 并行编译（预计提升 10-20%）

使用多线程并行编译 TypeScript。

### 优化 4：使用 esbuild-loader（预计提升 60-80%）

用 esbuild 替代 Babel，显著提升编译速度。

## 📚 相关文档

- [Webpack 构建优化文档](./webpack-build-optimization.md)
- Webpack 官方文档：https://webpack.js.org/configuration/devtool/
- Taro 官方文档：https://taro-docs.jd.com/

## 🐛 故障排查

### 问题 1：看不到构建时间输出

**原因：** 可能是配置文件没有正确加载

**解决：**
1. 确认 `config/dev.ts` 已保存
2. 重新启动开发服务器
3. 检查终端是否有报错

### 问题 2：增量编译时间过长

**可能原因：**
1. 缓存没有生效
2. 修改的文件影响了大量其他模块
3. Source Map 类型太慢

**解决：**
1. 检查是否启用了持久化缓存
2. 优化 Source Map 类型
3. 检查是否有循环依赖

### 问题 3：模块数量异常

**如果模块数量在增量编译时仍然很大（接近首次编译的数量）：**
- 说明缓存可能没有生效
- 检查 `node_modules/.cache/webpack-h5` 目录是否存在
- 尝试清理缓存后重新编译

---

**创建日期：** 2025-12-28  
**版本：** v1.0.0