企业官网建设流程全解析

1. 从Webpack到Rspack的迁移背景与问题现象

去年底我们团队决定将前端构建工具从Webpack迁移到Rspack，主要看中Rspack基于Rust的构建性能优势。整个迁移过程看似顺利，直到某天突然收到线上报警——核心业务页面白屏。经过紧急回滚和排查，发现问题出在一个看似无害的循环依赖上，而这个循环依赖在Webpack时代已经存在多年却从未出过问题。

具体现象是：当模块A引入模块B，模块B又反向依赖模块A时，在Webpack下能正常工作的代码，在Rspack环境下却出现了undefined的诡异情况。更令人困惑的是，这个问题只出现在生产环境，开发模式下一切正常。经过深度调试，最终发现问题的根源竟是一个const声明与var声明的细微差异。

2. 循环依赖的本质与不同构建工具的处理差异

2.1 什么是真正的循环依赖

循环依赖分为两种类型：

1. 初始化期循环依赖：模块在初始化阶段（即顶层代码执行时）直接或间接依赖自身
2. 运行时循环依赖：模块在函数执行时才触发循环引用

Webpack对这两种情况的处理策略完全不同。对于运行时循环依赖，Webpack通过将模块的exports对象提前创建来解决"先有鸡还是先有蛋"的问题。而初始化期循环依赖则可能引发真正的引用异常。

2.2 Webpack的宽容处理机制

Webpack在处理循环依赖时有个重要特性：所有模块的exports对象都会被提前创建并缓存。这意味着即使模块代码还未执行完毕，其他模块已经可以引用它的exports对象。这种机制使得很多本应报错的循环依赖得以"侥幸"运行。

具体流程如下：

1. 遇到模块A时立即创建module.exports = {}
2. 执行模块A代码时遇到require('./B')
3. 创建模块B的exports对象并开始执行B
4. 模块B中require('./A')时直接返回之前创建的exports对象
5. 虽然此时模块A尚未执行完毕，但B已经能拿到A的exports引用

2.3 Rspack的严格模式差异

Rspack虽然兼容Webpack的大部分行为，但在循环依赖处理上更加严格。关键区别在于：

1. 不完整的exports对象：Rspack不会提前填充所有exports属性
2. TDZ（Temporal Dead Zone）遵守：对const/let声明的变量严格遵循暂时性死区规则
3. 构建阶段检测：提供了专门的CircularDependencyPlugin进行主动检查

在我们的案例中，问题模块的结构如下：

// moduleA.js const { funcB } = require('./moduleB') const valueA = 'Hello' function funcA() { return funcB(valueA) } module.exports = { funcA, valueA } // moduleB.js const { funcA } = require('./moduleA') function funcB(param) { return `B received: ${param}` } module.exports = { funcB }

3. const与var在循环依赖中的关键差异

3.1 变量声明方式的本质区别

在JavaScript中：

• var：存在变量提升（hoisting），声明前访问得到undefined
• let/const：存在TDZ，声明前访问会抛出ReferenceError

在Webpack的宽松处理下，这种差异被掩盖了。因为所有exports都被提前创建，通过var导出的属性会被初始化为undefined，而const/let导出的属性在TDZ期间访问就会报错。

3.2 实际场景对比分析

假设有以下循环依赖：

// a.js const { b } = require('./b') console.log(b) // 在Rspack下可能报错 module.exports = { a: 1 } // b.js const { a } = require('./a') console.log(a) // 在Rspack下可能报错 module.exports = { b: 2 }

不同构建工具的处理结果：

3.3 Rspack的模块初始化顺序

Rspack的模块执行顺序更加符合ES标准：

1. 解析模块依赖图，发现循环依赖
2. 按顺序开始执行模块代码
3. 遇到const/let导出的属性时严格检查TDZ
4. 如果访问处于TDZ的绑定，直接抛出运行时错误

4. 问题定位与解决方案

4.1 诊断循环依赖的工具

在Rspack中推荐使用CircularCheckRspackPlugin（CircularDependencyRspackPlugin已废弃）：

// rspack.config.js module.exports = { plugins: [ new rspack.CircularCheckRspackPlugin({ failOnError: true, exclude: /node_modules/, onDetected({ module }) { console.error(`循环依赖: ${module.identifier()}`) } }) ] }

4.2 具体修复方案

针对我们的案例，提供了三种解决方案：

方案1：改为函数导出（推荐）

// moduleA.js module.exports = () => { const valueA = 'Hello' return { funcA() { /*...*/ }, valueA } } // moduleB.js module.exports = () => { return { funcB() { /*...*/ } } }

方案2：使用var声明（兼容方案）

// moduleA.js var valueA = 'Hello' // 改为var声明 module.exports = { funcA, valueA }

方案3：重构消除循环（根治方案）

1. 创建新模块common.js存放共享逻辑
2. 将循环依赖改为单向依赖
3. 使用依赖注入模式

4.3 Rspack配置优化建议

对于大型项目，建议配置：

{ plugins: [ new rspack.CircularCheckRspackPlugin({ failOnError: process.env.NODE_ENV === 'production', exclude: /node_modules/, ignoredConnections: [ // 明确允许某些循环依赖 [/src\/utils/, /src\/constants/] ] }) ] }

5. 深度理解模块系统的边界情况

5.1 ESM与CJS的循环依赖差异

ES模块系统对循环依赖的处理更加严格：

• ESM是静态解析，所有绑定是实时只读的
• CJS是动态加载，允许修改exports对象

在Rspack中混合使用ESM和CJS时，循环依赖的行为会更加复杂。建议项目统一使用一种模块规范。

5.2 Tree Shaking对循环依赖的影响

Rspack的Tree Shaking比Webpack更激进，可能意外破坏循环依赖的工作机制。可以通过以下配置调整：

{ experiments: { rspackFuture: { disableTransformByDefault: true } } }

5.3 动态导入的特殊情况

动态导入(import())的循环依赖行为与同步require不同：

• 不会阻塞模块初始化
• 有自己的错误处理机制
• 更适合处理潜在的循环场景

重构建议：

// 改造前 const { util } = require('./utils') // 改造后 let utils import('./utils').then(mod => { utils = mod }) export function getUtils() { return utils }

6. 工程化最佳实践

6.1 代码规范建议

1. 导出策略：

   • 优先使用函数/类作为导出主体
   • 避免直接导出const/let声明的原始值
   • 对于配置对象，使用Object.freeze防止意外修改

2. 导入规范：

   // 不推荐 const { a, b } = require('./module') // 推荐 const module = require('./module')

6.2 架构设计原则

1. 依赖方向：

   • 保持依赖单向流动（上层→下层）
   • 核心模块不应该依赖业务模块
   • 使用依赖注入解决跨层访问

2. 循环检测流程：

   graph TD A[发现循环依赖] --> B{是否必须?} B -->|是| C[改为动态导入] B -->|否| D[重构消除循环]

6.3 迁移检查清单

从Webpack迁移到Rspack时，建议按此顺序检查：

1. 运行CircularCheck插件检测所有循环依赖
2. 检查所有const/let导出的顶层变量
3. 测试生产构建是否正常工作
4. 验证Tree Shaking后的功能完整性
5. 性能对比测试

7. 疑难问题排查指南

7.1 典型错误场景分析

Case 1: undefined不是undefined

// moduleA.js const { value } = require('./B') console.log(typeof value) // 期望"string"，实际"undefined"

解决方案：

1. 确认B模块是否真的导出了value
2. 检查B模块是否有条件导出
3. 改为函数延迟取值

Case 2: 开发生产环境表现不一致

// 开发环境正常但生产环境报错 class MyClass {} module.exports = new MyClass()

原因：生产模式的代码优化可能导致类名被压缩，破坏instanceof检查

修复方案：

module.exports = { instance: new MyClass() }

7.2 调试技巧

1. 查看模块缓存：

   // 在Rspack构建的代码中插入 console.log(__webpack_module_cache__)

2. 追踪模块执行顺序：

   // rspack.config.js module.exports = { plugins: [{ apply(compiler) { compiler.hooks.compilation.tap('LogModuleOrder', (compilation) => { compilation.hooks.executeModule.tap('LogModuleOrder', (module) => { console.log('Executing:', module.resource) }) }) } }] }

3. 分析模块图：

   npx rspack --analyze

8. 从底层理解Rspack的模块系统

8.1 Rspack的模块解析流程

1. 解析阶段：

   • 创建ModuleGraph记录所有依赖关系
   • 标记循环依赖
   • 确定入口起点

2. 执行阶段：

   • 深度优先遍历模块图
   • 遇到循环依赖时创建代理对象
   • 严格检查TDZ违规

3. 优化阶段：

   • 标记未使用的导出
   • 应用Tree Shaking
   • 生成最终产物

8.2 关键源码逻辑

虽然Rspack是用Rust编写的，但其模块处理逻辑与Webpack类似，主要差异在：

1. 模块工厂：更严格的依赖关系验证
2. 模块执行：完全遵守ES规范的TDZ
3. 代码生成：更激进的静态分析

8.3 性能与安全的权衡

Rspack选择牺牲部分兼容性来换取：

1. 更快的构建速度（Rust实现）
2. 更符合标准的模块行为
3. 更好的长期可维护性

这种设计哲学意味着从Webpack迁移时需要特别注意边界情况，特别是那些依赖Webpack特殊处理逻辑的代码。