1. 从Webpack到Rspack的迁移背景与问题现象去年底我们团队决定将前端构建工具从Webpack迁移到Rspack主要看中Rspack基于Rust的构建性能优势。整个迁移过程看似顺利直到某天突然收到线上报警——核心业务页面白屏。经过紧急回滚和排查发现问题出在一个看似无害的循环依赖上而这个循环依赖在Webpack时代已经存在多年却从未出过问题。具体现象是当模块A引入模块B模块B又反向依赖模块A时在Webpack下能正常工作的代码在Rspack环境下却出现了undefined的诡异情况。更令人困惑的是这个问题只出现在生产环境开发模式下一切正常。经过深度调试最终发现问题的根源竟是一个const声明与var声明的细微差异。2. 循环依赖的本质与不同构建工具的处理差异2.1 什么是真正的循环依赖循环依赖分为两种类型初始化期循环依赖模块在初始化阶段即顶层代码执行时直接或间接依赖自身运行时循环依赖模块在函数执行时才触发循环引用Webpack对这两种情况的处理策略完全不同。对于运行时循环依赖Webpack通过将模块的exports对象提前创建来解决先有鸡还是先有蛋的问题。而初始化期循环依赖则可能引发真正的引用异常。2.2 Webpack的宽容处理机制Webpack在处理循环依赖时有个重要特性所有模块的exports对象都会被提前创建并缓存。这意味着即使模块代码还未执行完毕其他模块已经可以引用它的exports对象。这种机制使得很多本应报错的循环依赖得以侥幸运行。具体流程如下遇到模块A时立即创建module.exports {}执行模块A代码时遇到require(./B)创建模块B的exports对象并开始执行B模块B中require(./A)时直接返回之前创建的exports对象虽然此时模块A尚未执行完毕但B已经能拿到A的exports引用2.3 Rspack的严格模式差异Rspack虽然兼容Webpack的大部分行为但在循环依赖处理上更加严格。关键区别在于不完整的exports对象Rspack不会提前填充所有exports属性TDZTemporal Dead Zone遵守对const/let声明的变量严格遵循暂时性死区规则构建阶段检测提供了专门的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声明前访问得到undefinedlet/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 }不同构建工具的处理结果场景WebpackRspackvar声明变量输出undefined输出undefinedconst/let声明变量可能正常工作抛出ReferenceError函数导出正常工作正常工作3.3 Rspack的模块初始化顺序Rspack的模块执行顺序更加符合ES标准解析模块依赖图发现循环依赖按顺序开始执行模块代码遇到const/let导出的属性时严格检查TDZ如果访问处于TDZ的绑定直接抛出运行时错误4. 问题定位与解决方案4.1 诊断循环依赖的工具在Rspack中推荐使用CircularCheckRspackPluginCircularDependencyRspackPlugin已废弃// 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重构消除循环根治方案创建新模块common.js存放共享逻辑将循环依赖改为单向依赖使用依赖注入模式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 代码规范建议导出策略优先使用函数/类作为导出主体避免直接导出const/let声明的原始值对于配置对象使用Object.freeze防止意外修改导入规范// 不推荐 const { a, b } require(./module) // 推荐 const module require(./module)6.2 架构设计原则依赖方向保持依赖单向流动上层→下层核心模块不应该依赖业务模块使用依赖注入解决跨层访问循环检测流程graph TD A[发现循环依赖] -- B{是否必须?} B --|是| C[改为动态导入] B --|否| D[重构消除循环]6.3 迁移检查清单从Webpack迁移到Rspack时建议按此顺序检查运行CircularCheck插件检测所有循环依赖检查所有const/let导出的顶层变量测试生产构建是否正常工作验证Tree Shaking后的功能完整性性能对比测试7. 疑难问题排查指南7.1 典型错误场景分析Case 1: undefined不是undefined// moduleA.js const { value } require(./B) console.log(typeof value) // 期望string实际undefined解决方案确认B模块是否真的导出了value检查B模块是否有条件导出改为函数延迟取值Case 2: 开发生产环境表现不一致// 开发环境正常但生产环境报错 class MyClass {} module.exports new MyClass()原因生产模式的代码优化可能导致类名被压缩破坏instanceof检查修复方案module.exports { instance: new MyClass() }7.2 调试技巧查看模块缓存// 在Rspack构建的代码中插入 console.log(__webpack_module_cache__)追踪模块执行顺序// 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) }) }) } }] }分析模块图npx rspack --analyze8. 从底层理解Rspack的模块系统8.1 Rspack的模块解析流程解析阶段创建ModuleGraph记录所有依赖关系标记循环依赖确定入口起点执行阶段深度优先遍历模块图遇到循环依赖时创建代理对象严格检查TDZ违规优化阶段标记未使用的导出应用Tree Shaking生成最终产物8.2 关键源码逻辑虽然Rspack是用Rust编写的但其模块处理逻辑与Webpack类似主要差异在模块工厂更严格的依赖关系验证模块执行完全遵守ES规范的TDZ代码生成更激进的静态分析8.3 性能与安全的权衡Rspack选择牺牲部分兼容性来换取更快的构建速度Rust实现更符合标准的模块行为更好的长期可维护性这种设计哲学意味着从Webpack迁移时需要特别注意边界情况特别是那些依赖Webpack特殊处理逻辑的代码。