Rspack 0.x 到 1.0 版本迁移指南：关键变更与升级策略

Rspack 0.x 到 1.0 版本迁移指南：关键变更与升级策略

rspack web-infra-dev/rspack: 是一个用于管理和配置 Web 服务器（如 Apache，Nginx 等）的配置文件的工具，可以用于自动化部署和管理 Web 服务器。 项目地址: https://gitcode.com/gh_mirrors/rs/rspack

前言

Rspack 作为新一代前端构建工具，在 1.0 版本中对多项核心功能进行了重大改进和优化。本文将从技术实现角度深入分析这些变更，帮助开发者顺利完成从 0.x 版本到 1.0 版本的迁移工作。

配置默认值的重要调整

CSS 实验性功能变更

技术背景：在 0.x 版本中，Rspack 默认启用了 CSS 模块支持，这种设计虽然简化了配置，但也带来了不必要的性能开销。

变更内容：

• experiments.css 默认值从 true 改为 false
• 现在需要显式启用 CSS 处理功能

迁移建议：

// 新版配置示例
export default {
  experiments: {
    css: true  // 显式启用CSS支持
  }
};

影响范围：所有使用原生 CSS 处理的项目都需要调整配置。

模块连接优化

性能优化：模块连接(Module Concatenation)是一种将多个模块合并为单个模块的优化技术，能显著减少包体积。

变更内容：

• 生产模式下默认启用 optimization.concatenateModules
• 开发模式下保持禁用

技术影响：这项变更会使生产环境构建输出更小，但可能影响某些依赖模块独立性的代码。

已移除的配置项

TypeScript 配置路径变更

变更内容：

• 移除 resolve.tsConfigPath
• 改用 resolve.tsConfig

示例对比：

resolve: {
-  tsConfigPath: './tsconfig.json',
+  tsConfig: './tsconfig.json'
}

AMD 容器配置迁移

变更内容：

• 移除 output.amdContainer
• 功能整合到 output.library.amdContainer

SWC 加载器的重大调整

内置插件移除

架构决策：为了保持核心精简，Rspack 1.0 移除了内置的 SWC 插件，改为由开发者显式引入。

主要变更插件：

1. styled-components：改用 @swc/plugin-styled-components
2. emotion：改用 @swc/plugin-emotion
3. relay：改用 @swc/plugin-relay
4. preact：改用 @swc/plugin-prefresh

配置示例：

{
  loader: "builtin:swc-loader",
  options: {
    jsc: {
      experimental: {
        plugins: [
          ["@swc/plugin-styled-components", {}],
          ["@swc/plugin-emotion", {}]
        ]
      }
    }
  }
}

内置插件的重要变更

CSS 压缩插件替换

性能优化：从 SwcCssMinimizerRspackPlugin 迁移到更高效的 LightningCssMinimizerRspackPlugin

配置调整：

optimization: {
  minimizer: [
-   new rspack.SwcCssMinimizerRspackPlugin(),
+   new rspack.LightningCssMinimizerRspackPlugin()
  ]
}

JavaScript 压缩配置变更

标准化调整：对齐 SWC 的压缩配置结构

主要变更项：

• 所有压缩相关配置移至 minimizerOptions.compress 下
• 格式化相关配置移至 minimizerOptions.format 下
• 默认保留部分注释("some")

其他重要变更

开发服务器升级

技术栈更新：webpack-dev-server 从 v4 升级到 v5

注意事项：

1. 最低 Node.js 版本要求提升至 18.12.0
2. 部分配置项发生变化
3. 性能和安全性的显著提升

解析器重构

架构改进：ResolverFactory 和 Resolver 使用 Rust 重写

兼容性影响：

1. 不再支持插件钩子
2. 仅保留核心解析方法
3. 建议改用 NormalModuleFactory 的 resolve 钩子

替代方案示例：

compiler.hooks.normalModuleFactory.tap('MyPlugin', nmf => {
  nmf.hooks.resolve.tap('MyPlugin', data => {
    // 自定义解析逻辑
  });
});

迁移策略建议

1. 逐步迁移：先在不重要的项目中测试迁移
2. 配置审查：重点关注 CSS 处理和模块优化相关配置
3. 性能对比：迁移前后进行构建性能对比测试
4. 依赖检查：确保所有插件兼容 1.0 版本
5. 错误处理：准备好回滚方案

结语

Rspack 1.0 的这些变更是为了提供更稳定、更高效的构建体验。虽然迁移过程可能需要一些调整工作，但这些改进将为项目带来长期的性能收益和更好的可维护性。建议开发团队根据项目实际情况，制定合理的迁移计划，确保平稳过渡到新版本。

rspack web-infra-dev/rspack: 是一个用于管理和配置 Web 服务器（如 Apache，Nginx 等）的配置文件的工具，可以用于自动化部署和管理 Web 服务器。 项目地址: https://gitcode.com/gh_mirrors/rs/rspack