> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# Rspack 0.6 发布公告

_2024 年 4 月 10 日_


![Rspack Team](https://assets.rspack.rs/rspack/rspack-logo-with-background.png)

Rspack Team

[](https://x.com/rspack_dev)

@rspack_dev

## 主要功能更新

### 内置支持 mini-css-extract-plugin

你现在可以使用 `rspack.CssExtractRspackPlugin` 作为 `mini-css-extract-plugin` 的替代。

这在一些场景很实用，例如当内置的 CSS 处理不能满足你的需求，有更定制化的 CSS Modules name 等，或者你想要使用一些依赖 css-loader 的 loader，但仍然想要将 CSS 提取成单独文件。

详细配置见 [CssExtractRspackPlugin](/zh/plugins/css-extract-rspack-plugin.md#cssextractrspackplugin)。

```js title="rspack.config.mjs"
import { rspack } from '@rspack/core';

export default {
  plugins: [new rspack.CssExtractRspackPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [rspack.CssExtractRspackPlugin.loader, 'css-loader'],
      },
    ],
  },
};
```

> 你可以在[这里](https://github.com/rstackjs/rstack-examples/tree/main/rspack/react-with-extract-css)找到一个基础的项目例子。

### 默认开启新版 tree shaking

Rspack 在 0.1.0 支持了基本的 tree shaking 功能，由于最初的架构还未稳定, 我们使用了相对简单的方法实现了基础版的 tree shaking（仅支持未使用导出删除），但是随着 Rspack 功能的完善，架构逐渐稳定
基础的 tree shaking 无法满足用户的需求，比如：

1. 无法处理循环引用，无法给其他构建阶段足够的优化信息，实现进一步的优化 (mangleExports, concatenateModules, barrel exports optimization)。
2. 经常出现一些 interop 相关的 badcase，例如: worker-thread 模块，Common Js 模块，module federation 等

为了解决以上问题，我们决定使用类似 webpack 的方案，自底向上重新实现整个优化流程，并在 0.4.2 引入 `experiments.rspackFuture.newTreeshaking` 配置，来实验性的开启新的优化算法。
经过 4 个月 bug 修复和优化，新的 tree shaking 算法已经相对稳定，因此我们决定在 0.6.0 默认开启新的 tree shaking 算法。

## 不兼容更新

### 移除 experiments.rspackFuture.disableApplyEntryLazily

`experiments.rspackFuture.disableApplyEntryLazily` 选项自 v0.5.0 已被默认开启，并在 v0.6.0 中被删除。

### 移除 compiler.build 和 compiler.rebuild

`compiler.build` 与 `compiler.rebuild` 不属于 webpack 公开 API，目前已经被移除。

### 移除 builtins.css 并引入 CSS 相关 module.parser 和 module.generator 选项

移除 `builtins.css`，请使用引入的 CSS 相关的 [`module.parser`](/zh/config/module-parser.md#cssauto) 和 [`module.generator`](/zh/config/module-generator.md#cssauto) 选项进行替代。

同时，从 v0.6.0 版本开始，Rspack 的 `experiments.css` 将会以 webpack 的 `experiments.css` 为目标进行对齐，这意味着和 webpack `experiments.css` 一样在未来将不再支持[不支持 CSS 变量的浏览器](https://caniuse.com/css-variables)。因此，对于那些需要使用尚未得到 `experiments.css` 支持的配置，或者需要兼容老版本浏览器的项目，我们推荐迁移至 [`rspack.CssExtractRspackPlugin`](/zh/plugins/css-extract-rspack-plugin.md)。

在 v0.6.0 中，我们引入了三种新的模块类型的 `module.generator` 和 `module.parser` 选项：`css/auto`、`css` 和 `css/module`，这些选项只有在启用 experiments.css 时才会生效，关于如何使用可查看[这个例子](https://github.com/rstackjs/rstack-examples/tree/main/rspack/css-parser-generator-options)。

在 `module.parser` 选项中，`css`、`css/auto` 和 `css/module` 模块类型都包含了 `namedExports` 属性。它取代了 `builtins.css.namedExports` 配置。

对于 `module.generator` 选项，`css/auto` 和 `css/module` 模块类型提供了 `exportsOnly`、`exportsConvention` 和 `localIdentName` 属性。`css` 类型只包含 `exportsOnly` 和 `exportsConvention` 属性。`exportsOnly`、`exportsConvention` 和 `localIdentName` 分别取代了 `builtins.css.modules.exportsOnly`、`builtins.css.modules.localsConvention` 和 `builtins.css.modules.localIdentName`。

除此之外，还包括一些关于默认值的修改：

1. `exportsConvention` 的值从 `'asIs'`, `'camelCaseOnly'` 等变更为 `'as-is'`, `'camel-case-only'` 等，以保持与 webpack `experiments.css` 的一致。

2. `namedExports: false` 支持同时使用默认导出（default export）、命名导出（named export）和命名空间导出（namespace export），在此之前它只支持使用默认导出：

   ```js
   // v0.6.0 之前只支持使用默认导出
   import classes from './index.module.css';

   // 现在除默认导出之外，也支持：
   // 命名空间导出
   import * as classes from './index.module.css';
   // 命名导出
   import { class1, class2 } from './index.module.css';
   // 默认导出和命名导出同时使用
   import classes, { class1, class2 } from './index.module.css';
   ```

3. `namedExports` 的默认值从 `false` 变更为 `true`，这意味着你需要默认使用命名空间导入（例如 `import * as classes from './style.css'`）或命名导入（例如 `import { class1 } from './style.css'`），这将提高与未来[原生 CSS 模块](https://web.dev/articles/css-module-scripts)的兼容性。而这并不意味着你需要一次性迁移所有的导入，你可以通过设置 `namedExports: false` 来禁用此行为，并且由于现在 `namedExports: false` 也支持命名导出和命名空间导出，因此你可以逐步迁移这些导入。

4. `localIdentName` 的默认值在从在开发模式下 `'[path][name][ext]__[local]'` 和在生产模式下 `'[hash]'` 变更为在开发和生产模式下都是 `'[uniqueName]-[id]-[local]'`，这将略微改善 CSS 产物的 gzip 压缩大小。

5. `exportsOnly` 的默认值在 `target: 'node'` 下由原来的 `false` 变更为 `true`。

6. CSS 默认规则的模块类型从 `css` 变更为 `css/auto`，`css/auto` 将自动解析以 `.module.` 或 `.modules.` 为中缀的 CSS 文件作为 [CSS Modules](https://github.com/css-modules/css-modules) 处理，这与 [`css-loader` 的 `modules.auto: true`](https://github.com/webpack/css-loader?tab=readme-ov-file#auto) 行为一致，这将[简化使用 less 或 sass 与 CSS Modules 的规则书写](https://github.com/webpack/webpack/issues/16572)。

### 升级 SWC 到 0.90.x

升级 Rust crate `swc_core` 到 `0.90.x`，这会对使用 SWC Wasm 插件的用户产生影响。

### 当 CSS 的顺序在多个 chunk 中不一致时发出警告

当多个 chunk 中 CSS 顺序不一致时会发出警告，假如你有两个 entry，entryA 和 entryB，entryA 中引入 a.css 然后引入 b.css，而 entryB 中引入 b.css 然后引入 a.css。
当满足 splitChunks 条件时，a.css 和 b.css 会成为单独 chunk，这个 chunk 中 a.css 和 b.css 的顺序无法保证，会产生如下的警告

```txt
WARNING in ⚠ chunk src_a_css-src_b_-5c8c53 [css-extract-rspack-plugin]
  │ Conflicting order. Following module has been added:
  │  * css ./css-loader/dist/cjs.js??ruleSet[1].rules[2].use[1]!./src/a.css
  │ despite it was not able to fulfill desired ordering with these modules:
  │  * css ./css-loader/dist/cjs.js??ruleSet[1].rules[2].use[1]!./src/b.css
  │   - couldn't fulfill desired order of chunk group(s) parent2
  │   - while fulfilling desired order of chunk group(s) parent1
```

如果你确定他们的顺序不一致没有关系，可以通过配置 `ignoreWarnings` 来忽略这种错误。

```js title="rspack.config.mjs"
export default {
  ignoreWarnings: [/Conflicting order/],
};
```

## 迁移指南

### 使用 rspack.CssExtractRspackPlugin

如果你曾经使用 webpack 和 `mini-css-extract-plugin`，只需要将 `mini-css-extract-plugin` 换成 `rspack.CssExtractPlugin` 即可。

```diff title="rspack.config.mjs"
+ import { rspack } from '@rspack/core';
- import CssExtract from 'mini-css-extract-plugin';

export default {
  plugins: [new rspack.CssExtractRspackPlugin()],
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [CssExtract.loader, 'css-loader'],
      },
    ],
  },
};
```

### 迁移 builtins.css 配置

1. 使用 `module.parser["css/auto"].namedExports` 替代 `builtins.css.namedExports`。
2. 使用 `module.generator["css/auto"].exportsOnly` 替代 `builtins.css.modules.exportsOnly`。
3. 使用 `module.generator["css/auto"].exportsConvention` 替代 `builtins.css.modules.localsConvention`。
4. 使用 `module.generator["css/auto"].localIdentName` 替代 `builtins.css.modules.localIdentName`。

以上出现的 `"css/auto"` 为 CSS 默认的模块类型，可根据需要修改为 `"css"` 或 `"css/module"`。

添加以下配置将保持原有 `builtins.css` 默认行为，可根据以下配置根据需要进行修改：

```diff title="rspack.config.mjs"
export default {
+  module: {
+    generator: {
+      "css/auto": {
+        exportsOnly: false,
+        exportsConvention: 'as-is',
+        localIdentName: isProduction ? '[hash]' : '[path][name][ext]__[local]',
+      },
+      "css": {
+        exportsOnly: false,
+        exportsConvention: 'as-is',
+      },
+      "css/module": {
+        exportsOnly: false,
+        exportsConvention: 'as-is',
+        localIdentName: isProduction ? '[hash]' : '[path][name][ext]__[local]',
+      },
+    },
+    parser: {
+      "css/auto": {
+        namedExports: false,
+      },
+      "css": {
+        namedExports: false,
+      },
+      "css/module": {
+        namedExports: false,
+      },
+    },
+  },
}
```

如需要对部分模块进行配置，可使用 `module.rules` 中的 [`rules[].parser`](/zh/config/module-rules.md#rulesparser) 和 [`rules[].generator`](/zh/config/module-rules.md#rulesgenerator) 选项进行配置。

### 调用 compiler.run 执行构建

`compiler.build` 或 `compiler.rebuild` 已经被废弃，请切换到 `compiler.run` 进行构建，与重新构建。

### 升级 SWC 插件

在 `0.6.0` 中，Rust crate `swc_core` 的版本升级到 `0.90.x`，使用到的 SWC Wasm 插件需要确保其使用的 `swc_core` 的版本一致性，否则可能产生无法预知的问题。

详情请参考[文档](https://swc.rs/docs/plugin/selecting-swc-core#090x)。