vf_react/docs/BUILD_OPTIMIZATION.md

构建优化指南

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

优化概览

项目已实施以下优化措施，预计可提升构建速度 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 的所有语言包（如果未使用）

使用方法

开发模式 (推荐)

npm start

• 使用快速 source map: eval-cheap-module-source-map
• 启用热更新 (HMR)
• 文件系统缓存自动生效

生产构建

npm run build

• 禁用 source map
• 启用所有优化
• 生成优化后的打包文件

构建分析 (Bundle Analysis)

npm run build:analyze

• 生成可视化的打包分析报告
• 报告保存在 build/bundle-report.html
• 自动在浏览器中打开

代码检查

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

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

清理缓存

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

# 清理 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() 对路由组件进行懒加载：

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

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

2. 依赖优化

考虑替换或按需引入大型依赖：

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

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

3. 图片优化

• 使用 WebP 格式
• 实施图片懒加载
• 压缩图片资源

4. Tree Shaking

确保依赖支持 ES6 模块：

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

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

5. 升级 Node.js

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

监控构建性能

使用 Webpack Bundle Analyzer

npm run build:analyze

查看：

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

监控构建时间

# 显示详细构建信息
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 中修改：

// 生产环境也启用 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