09db05c448
- 移动42个文档文件到 docs/ 目录 - 更新 .gitignore 允许 docs/ 下的 .md 文件 - 删除根目录下的重复文档文件 📁 文档分类： - StockDetailPanel 重构文档（3个） - PostHog 集成文档（6个） - 系统架构和API文档（33个） 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
213 lines
5.0 KiB
Markdown
213 lines
5.0 KiB
Markdown
# 构建优化指南
|
||
|
||
本文档介绍了项目中实施的构建优化措施，以及如何使用这些优化来提升开发和生产构建速度。
|
||
|
||
## 优化概览
|
||
|
||
项目已实施以下优化措施，预计可提升构建速度 **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
|