docs: 将所有文档迁移到 docs/ 目录
- 移动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>
This commit is contained in:
zdl
212
docs/BUILD_OPTIMIZATION.md
Normal file
212
docs/BUILD_OPTIMIZATION.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# 构建优化指南
|
||||
|
||||
本文档介绍了项目中实施的构建优化措施，以及如何使用这些优化来提升开发和生产构建速度。
|
||||
|
||||
## 优化概览
|
||||
|
||||
项目已实施以下优化措施，预计可提升构建速度 **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
|
||||
Reference in New Issue
Block a user