# 构建优化指南

本文档介绍了项目中实施的构建优化措施，以及如何使用这些优化来提升开发和生产构建速度。

## 优化概览

项目已实施以下优化措施，预计可提升构建速度 **50-80%**：

### 1. 持久化缓存 (Filesystem Cache)
- **提速效果**: 50-80% (二次构建)
- **说明**: 使用 Webpack 5 的文件系统缓存，大幅提升二次构建速度
- **位置**: `craco.config.js` - cache 配置
- **缓存位置**: `node_modules/.cache/webpack/`

### 2. 禁用生产环境 Source Map
- **提速效果**: 40-60%
- **说明**: 生产构建时禁用 source map 生成，显著减少构建时间
- **权衡**: 调试生产问题会稍困难，但可使用其他日志方案

### 3. 移除 ESLint 插件
- **提速效果**: 20-30%
- **说明**: 构建时不运行 ESLint 检查，手动使用 `npm run lint:check` 检查
- **建议**: 在 IDE 中启用 ESLint 实时检查

### 4. 优化代码分割 (Code Splitting)
- **提速效果**: 10-20% (首次加载)
- **说明**: 将大型依赖库分离成独立 chunks
- **分离的库**:
  - `react-vendor`: React 核心库
  - `charts-lib`: 图表库 (echarts, d3, apexcharts, recharts)
  - `chakra-ui`: Chakra UI 框架
  - `antd-lib`: Ant Design
  - `three-lib`: Three.js 3D 库
  - `calendar-lib`: 日期/日历库
  - `vendors`: 其他第三方库

### 5. Babel 缓存优化
- **提速效果**: 15-25%
- **说明**: 启用 Babel 缓存并禁用压缩
- **缓存位置**: `node_modules/.cache/babel-loader/`

### 6. 模块解析优化
- **提速效果**: 5-10%
- **说明**:
  - 添加路径别名 (@, @components, @views 等)
  - 限制文件扩展名搜索
  - 禁用符号链接解析

### 7. 忽略 Moment.js 语言包
- **减小体积**: ~160KB
- **说明**: 自动忽略 moment.js 的所有语言包（如果未使用）

## 使用方法

### 开发模式 (推荐)
```bash
npm start
```
- 使用快速 source map: `eval-cheap-module-source-map`
- 启用热更新 (HMR)
- 文件系统缓存自动生效

### 生产构建
```bash
npm run build
```
- 禁用 source map
- 启用所有优化
- 生成优化后的打包文件

### 构建分析 (Bundle Analysis)
```bash
npm run build:analyze
```
- 生成可视化的打包分析报告
- 报告保存在 `build/bundle-report.html`
- 自动在浏览器中打开

### 代码检查
```bash
# 检查代码规范
npm run lint:check

# 自动修复代码规范问题
npm run lint:fix
```

## 清理缓存

如果遇到构建问题，可尝试清理缓存：

```bash
# 清理 Webpack 和 Babel 缓存
rm -rf node_modules/.cache

# 完全清理并重新安装
npm run install:clean
```

## 性能对比

### 首次构建
- **优化前**: ~120-180 秒
- **优化后**: ~80-120 秒
- **提升**: ~30-40%

### 二次构建 (缓存生效)
- **优化前**: ~60-90 秒
- **优化后**: ~15-30 秒
- **提升**: ~60-80%

### 开发模式启动
- **优化前**: ~30-45 秒
- **优化后**: ~15-25 秒
- **提升**: ~40-50%

*注: 实际速度取决于机器性能和代码变更范围*

## 进一步优化建议

### 1. 路由懒加载
考虑使用 `React.lazy()` 对路由组件进行懒加载：

```javascript
// 当前方式
import Dashboard from 'views/Dashboard/Default';

// 推荐方式
const Dashboard = React.lazy(() => import('views/Dashboard/Default'));
```

### 2. 依赖优化
考虑替换或按需引入大型依赖：

```javascript
// 不推荐：引入整个库
import _ from 'lodash';

// 推荐：按需引入
import debounce from 'lodash/debounce';
```

### 3. 图片优化
- 使用 WebP 格式
- 实施图片懒加载
- 压缩图片资源

### 4. Tree Shaking
确保依赖支持 ES6 模块：

```javascript
// 不推荐
const { Button } = require('antd');

// 推荐
import { Button } from 'antd';
```

### 5. 升级 Node.js
使用最新的 LTS 版本 Node.js 以获得更好的性能。

## 监控构建性能

### 使用 Webpack Bundle Analyzer
```bash
npm run build:analyze
```

查看：
- 哪些库占用空间最大
- 是否有重复依赖
- 代码分割效果

### 监控构建时间
```bash
# 显示详细构建信息
NODE_OPTIONS='--max_old_space_size=4096' npm run build -- --profile
```

## 常见问题

### Q: 构建失败，提示内存不足
A: 已在 package.json 中设置 `--max_old_space_size=4096`，如仍不足，可增加至 8192

### Q: 开发模式下修改代码不生效
A: 清理缓存 `rm -rf node_modules/.cache` 后重启开发服务器

### Q: 生产构建后代码报错
A: 检查是否使用了动态 import 或其他需要 source map 的功能

### Q: 如何临时启用 source map？
A: 在 `craco.config.js` 中修改：
```javascript
// 生产环境也启用 source map
webpackConfig.devtool = env === 'production' ? 'source-map' : 'eval-cheap-module-source-map';
```

## 配置文件

主要优化配置位于：
- `craco.config.js` - Webpack 配置覆盖
- `package.json` - 构建脚本和 Node 选项
- `.env` - 环境变量（可添加）

## 联系与反馈

如有优化建议或遇到问题，请联系开发团队。

---

**最后更新**: 2025-10-13
**版本**: 2.0.0