企业官网建设流程全解析

1. 问题背景：从 Webpack 到 Rspack 的迁移陷阱

最近在将一个大型 Electron 项目从 Webpack 构建工具迁移到 Rspack 时，遇到了一个令人困惑的问题。项目在 Webpack 下运行良好，但切换到 Rspack 后，主进程启动时直接白屏崩溃，报错信息显示：

ReferenceError: Cannot access '__rspack_default_export' before initialization

这个错误特别令人费解，因为：

1. 业务代码完全没有改动
2. 配置几乎是原样从 Webpack 迁移过来的
3. Webpack 构建的版本运行完全正常

作为团队的技术负责人，我花了整整两天时间深入排查这个问题，最终发现这竟然是一个由const和var声明差异引发的"血案"。下面我将详细分享这个问题的定位过程、根本原因和解决方案。

2. 问题定位：抽丝剥茧的过程

2.1 确认循环依赖链

首先，根据报错堆栈，我定位到了一条循环依赖链：

product.ts → log/index.ts → xbotLog.ts → remoteLog.ts → product.ts

具体来说，remoteLog.ts文件顶部引入了product：

import product, { isOversea, isPrivate, isStandalone } from '@root/common/product';

而product.ts又通过log模块间接依赖了remoteLog.ts，形成了一个完整的循环依赖闭环。

2.2 Webpack 为何能正常运行？

这个循环依赖并不是新引入的，它在 Webpack 构建环境下已经存在并运行了很长时间。我仔细对比了两边的配置：

• 同样的babel-loader+@babel/preset-typescript配置
• 相同的splitChunks优化策略
• 一致的target: 'electron-main'目标环境
• 相同的output.libraryTarget: 'commonjs'输出格式

配置几乎一模一样，为什么 Webpack 能正常运行而 Rspack 会报错？

2.3 构建产物对比分析

为了找出差异，我决定对比两者的构建产物。这个决定最终揭示了问题的真相。

Webpack 生成的模块导出代码：

__webpack_require__.d(__webpack_exports__, { "default": () => (__WEBPACK_DEFAULT_EXPORT__) }); // ... var __WEBPACK_DEFAULT_EXPORT__ = product;

Rspack 生成的模块导出代码：

__webpack_require__.d(__webpack_exports__, { "default": () => (__rspack_default_export) }); // ... /* export default */ const __rspack_default_export = (product);

关键区别一目了然：Webpack 使用var声明导出变量，而 Rspack 使用const。这个看似微小的差异，正是导致问题的根本原因。

3. 根本原因：Temporal Dead Zone（暂时性死区）

3.1 var 与 const/let 的本质区别

这不是简单的打包工具配置差异，而是 JavaScript 语言层面var和const/let的本质区别。

var 的行为：

console.log(a); // 输出 undefined（不会报错） var a = 1;

var声明会被提升（hoisting）到函数作用域顶部，变量在声明前就已存在，只是值为undefined。

const/let 的行为：

console.log(b); // 抛出 ReferenceError: Cannot access 'b' before initialization const b = 1;

const和let虽然也会被提升，但在赋值语句执行之前处于暂时性死区（Temporal Dead Zone，TDZ），任何访问都会抛出ReferenceError。

3.2 循环依赖下的连锁反应

理解了 TDZ 后，我们就能解释循环依赖场景下发生了什么。两个打包器都使用__webpack_require__.d来注册模块导出，其本质是定义了一个 getter：

// Webpack 和 Rspack 共用的运行时源码 __webpack_require__.d = (exports, definition) => { for (var key in definition) { Object.defineProperty(exports, key, { enumerable: true, get: definition[key] // ← 这是一个惰性 getter }); } };

当注册"default": () => (__rspack_default_export)时，它只是定义了一个 getter 函数，并不会立即求值。真正的求值发生在其他模块访问.default的时候。

3.3 循环依赖执行流程详解

让我们详细看看循环依赖情况下的执行流程：

1. product.ts开始执行
2. → 遇到import log→log/index.ts开始执行
3. → 遇到import xbotLog→xbotLog.ts开始执行
4. → 遇到import remoteLog→remoteLog.ts开始执行
5. → 遇到import product→ 发现product正在执行中，返回当前（未完成的）exports 对象
6. → 访问product.default→ 触发 getter → 尝试读取__rspack_default_export
7. → 💥const还未赋值，处于 TDZ → 抛出 ReferenceError

如果是var声明：

6. → 访问product.default→ 触发 getter → 读取__WEBPACK_DEFAULT_EXPORT__
7. →var已提升，值为undefined→ 不会报错，后续product执行完毕后值会正确更新

4. 解决方案：从临时修复到根本解决

4.1 快速修复方案

Rspack 提供了output.environment配置来控制生成代码使用的 ES 特性级别：

// rspack.main.js module.exports = { output: { path: outputFilePath, filename: '[name].js', libraryTarget: 'commonjs', environment: { const: false, // 使用 var 代替 const/let }, }, // ... 其他配置保持不变 };

设置environment.const: false后，Rspack 会将生成代码中的所有const/let退化为var，与 Webpack 行为一致。

修改后的构建产物中：

/* export default */ const __rspack_default_export = (product);

变成了：

/* export default */ var __rspack_default_export = (product);

这样修改后，循环依赖不再报错，问题得到解决。整个过程只改了 3 行配置，无需任何业务代码改动。

4.2 谁对谁错？技术选择的哲学

严格来说，Rspack 的做法更"正确"。ES Module 规范中，导入绑定（import binding）本身就不应该在模块初始化完成前被访问。使用const能让这类隐患在运行时尽早暴露。

而 Webpack 用var的做法更"宽容"——循环依赖下虽然不报错，但你拿到的是undefined。如果代码恰好在初始化阶段就使用了这个值去做判断或调用方法，可能会产生更隐蔽、更难调试的 bug。

4.3 根本解决方案

虽然output.environment.const: false是一个低成本的兼容方案，但循环依赖本身才是问题的根源。从长远来看，我们应该：

1. 延迟引用：将产生循环的 import 改为函数内require()，只在真正需要时才加载
2. 模块解耦：重新组织模块结构，打破依赖环路
3. 检测工具：在 CI 中集成circular-dependency-plugin或madge等工具，把循环依赖扼杀在代码审查阶段

5. 技术对比与经验总结

5.1 Webpack 与 Rspack 行为对比

5.2 迁移经验与最佳实践

1. 不要假设兼容性：即使号称高度兼容的工具，在实现细节上也可能有重要差异
2. 重视构建产物分析：当遇到诡异问题时，直接对比构建产物往往能快速定位问题
3. 理解语言特性：深入理解 JavaScript 的语言特性（如 TDZ）能帮助解决看似复杂的问题
4. 技术债务管理：循环依赖等技术债务可能在工具迁移时突然暴露，要建立机制预防和消除

5.3 性能与稳定性的权衡

Rspack 基于 Rust 实现，确实带来了显著的构建性能提升。在我们的项目中，完整构建时间从 Webpack 的 45 秒降低到了 18 秒，热更新速度也有明显改善。但这次经历提醒我们，在追求性能的同时，也不能忽视稳定性和兼容性问题。

6. 扩展思考：前端构建的未来

6.1 工具生态的演进

Rspack 代表了前端构建工具的新一代尝试，它试图在 Webpack 的生态基础上，通过 Rust 实现获得性能提升。类似的工具还有：

• Vite：基于原生 ES Modules 和 Rollup
• Turbopack：Webpack 作者的新项目，同样基于 Rust
• esbuild：极快的 JavaScript 打包器

6.2 模块系统的设计考量

这次问题本质上是模块系统设计的问题。现代前端开发中，我们需要更加注意：

• 模块的初始化顺序
• 循环依赖的危害
• 静态分析与动态导入的结合

6.3 团队协作的建议

对于正在进行构建工具迁移的团队，我建议：

1. 逐步迁移：不要一次性全量切换，可以先在非关键路径试用
2. 建立监控：对构建产物进行差异对比和运行时监控
3. 知识共享：组织内部技术分享，让团队成员理解工具差异

7. 实操指南：如何安全迁移到 Rspack

基于这次经验，我总结了一个安全迁移到 Rspack 的步骤指南：

7.1 迁移前准备

1. 在项目中安装circular-dependency-plugin，检测现有循环依赖
2. 使用webpack-bundle-analyzer分析现有构建结构
3. 建立性能基准（构建时间、产物大小等）

7.2 配置迁移

1. 从简单配置开始，逐步添加复杂功能
2. 特别注意output.environment相关配置
3. 对比 Webpack 和 Rspack 的构建产物差异

7.3 测试策略

1. 单元测试：确保基本功能正常
2. 集成测试：验证模块交互
3. E2E 测试：检查运行时行为

7.4 监控与优化

1. 监控生产环境的运行时错误
2. 持续优化构建配置
3. 定期检查并消除循环依赖

8. 常见问题与解决方案

8.1 迁移后出现奇怪的运行时错误

问题现象：代码在 Webpack 下正常，但在 Rspack 下报错

解决方案：

1. 检查是否是循环依赖导致的问题
2. 对比构建产物，找出行为差异
3. 尝试调整output.environment配置

8.2 构建速度没有明显提升

可能原因：

1. 配置不正确，没有充分利用 Rspack 的优势
2. 项目结构特殊，某些功能在 Rspack 中效率不高

解决方案：

1. 检查是否启用了持久化缓存
2. 尝试逐步禁用插件，找出性能瓶颈
3. 参考 Rspack 官方性能优化指南

8.3 某些 Webpack 插件不兼容

解决方案：

1. 检查 Rspack 官方文档，看是否有替代方案
2. 联系插件作者，询问兼容性计划
3. 考虑自己实现简化版功能

9. 个人经验与反思

在这次迁移过程中，我深刻体会到几个重要的工程实践原则：

1. 理解底层原理：如果不了解 TDZ 的概念，这个问题可能会困扰我们更长时间
2. 工具不是银弹：即使像 Rspack 这样的新工具，也有自己的特点和限制
3. 技术债务迟早要还：循环依赖这样的问题，越早解决成本越低

我还发现，在技术决策过程中，我们需要在多个维度进行权衡：

• 性能 vs 稳定性
• 开发体验 vs 长期维护成本
• 新技术的收益 vs 迁移风险

最后，对于正在考虑从 Webpack 迁移到 Rspack 的团队，我的建议是：做好充分准备，但不必因噎废食。Rspack 确实带来了显著的性能提升，只要我们理解它的特点，就能充分发挥其优势。