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

# CSS

Rspack 内置了对 CSS 的支持，并提供了多种能力来支持 CSS 打包。

## 开启 CSS 支持

你可以从以下方式中进行选择：

### 内置 CSS 支持

Rspack 支持以下四种 CSS 模块类型，你可以手动进行配置：

- `css/auto`：基于文件扩展名自动判断是普通 CSS 文件还是 [CSS Modules](#css-modules)，`*.module.css` 或 `*.modules.css` 结尾的文件会被视为 CSS Modules。
- `css`：用于解析普通的 CSS 文件，不启用 CSS Modules 能力。
- `css/global`：用于以全局作用域模式解析 CSS Modules。
- `css/module`：用于解析 CSS Modules。

`css/auto`、`css/global` 和 `css/module` 的区别在于 CSS Modules 作用域对生成 CSS 的影响：

- `css/auto` 会根据文件名选择行为。`style.css` 会作为普通 CSS 处理，而 `style.module.css` 和 `style.modules.css` 会按 `css/module` 处理。
- `css/module` 会启用 CSS Modules，默认使用局部作用域。像 `.button` 这样的选择器会在生成的 CSS 中被重命名。如果希望选择器保持全局，可以使用 `:global(.button)`。
- `css/global` 会启用 CSS Modules，默认使用全局作用域。像 `.button` 这样的选择器会保持全局。如果希望选择器在生成的 CSS 中被重命名，可以使用 `:local(.button)`。

例如：

```css title="style.css"
.button {
  color: red;
}

:local(.title) {
  color: blue;
}
```

当使用 `type: 'css'` 时，文件会作为普通 CSS 输出，不会应用 CSS Modules 作用域转换。

当使用 `type: 'css/module'` 时，`.button` 和 `.title` 都是局部选择器，会在生成的 CSS 中被重命名。如果 `.button` 需要保持全局，可以使用 `:global(.button)`。

当使用 `type: 'css/global'` 时，`.button` 会保持全局，而 `.title` 因为被 `:local(...)` 包裹，会被重命名。

生成的 CSS 大致如下：


**css/auto style.css**

```css
.button {
  color: red;
}

:local(.title) {
  color: blue;
}
```


**css/auto style.module.css**

```css
._button_hash {
  color: red;
}

._title_hash {
  color: blue;
}
```


**css/module style.css**

```css
._button_hash {
  color: red;
}

._title_hash {
  color: blue;
}
```


**css/global style.css**

```css
.button {
  color: red;
}

._title_hash {
  color: blue;
}
```


要启用 CSS 支持，需要将 CSS 规则添加到配置中：

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.module\.css$/i,
        type: 'css/module',
      },
      {
        test: /\.global\.css$/i,
        type: 'css/global',
      },
      {
        test: /\.css$/i,
        type: 'css/auto',
      },
    ],
  },
};
```

你也可以通过配置自定义将哪些文件视为 CSS 文件。比如，将 `.less` 文件视为 CSS 文件：

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.less$/,
        type: 'css/auto', // 👈
        use: ['less-loader'],
      },
    ],
  },
};
```

### CSS export type

内置 CSS 支持默认使用 `exportType: 'link'`。这会将 CSS 作为样式表产物输出，并通过内置 CSS loading runtime 加载。你可以设置 `module.parser.css.exportType`，或设置 `css/auto`、`css/global`、`css/module` 的 parser 选项，来改变 CSS 导出到 JavaScript 的方式。

支持的取值：

- `link`：将 CSS 作为样式表产物输出。
- `text`：将生成后的 CSS 文本作为默认导出。
- `css-style-sheet`：将 `CSSStyleSheet` 实例作为默认导出。
- `style`：在运行时通过 `<style>` 标签将 CSS 注入到文档中。

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/i,
        type: 'css/auto',
        parser: {
          exportType: 'text',
        },
      },
    ],
  },
};
```

```js title="index.js"
import cssText from './style.css';

console.log(cssText);
```

更多细节请参考 [module.parser\["css/auto"\].exportType](https://rspack.rs/zh/config/module-parser.md#cssautoexporttype)。

### 使用 CssExtractRspackPlugin

Rspack 支持使用 [css-loader](https://github.com/webpack/css-loader) 和 [CssExtractRspackPlugin](https://rspack.rs/zh/plugins/css-extract-rspack-plugin.md)，用于生成独立的 CSS 文件。

如果你正在迁移一个使用 [mini-css-extract-plugin](https://github.com/webpack/mini-css-extract-plugin) 的 webpack 项目，那么推荐使用 CssExtractRspackPlugin 来替换 mini-css-extract-plugin，它们的功能和配置方式基本一致。

- 安装 css-loader：


```sh [npm]
npm add css-loader -D
```

```sh [yarn]
yarn add css-loader -D
```

```sh [pnpm]
pnpm add css-loader -D
```

```sh [bun]
bun add css-loader -D
```

```sh [deno]
deno add npm:css-loader -D
```

- 添加配置：

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

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

> 参考 [迁移指南](https://rspack.rs/zh/guide/migration/webpack.md#mini-css-extract-plugin) 了解如何从 webpack 进行迁移。

:::tip
CssExtractRspackPlugin 不能与 `type: 'css'`、`type: 'css/auto'`、`type: 'css/global'` 或 `type: 'css/module'` 同时使用，因为 css-loader 会将 css 转换成 javascript 类型。
:::

### 使用 style-loader

Rspack 支持使用 [css-loader](https://github.com/webpack/css-loader) 和 [style-loader](https://github.com/webpack/style-loader)，将 CSS 通过 `<style>` 标签注入。这种方式不会生成独立的 CSS 文件，而是将 CSS 的内容内联到 JS 文件中。

- 安装 css-loader 和 style-loader：


```sh [npm]
npm add css-loader style-loader -D
```

```sh [yarn]
yarn add css-loader style-loader -D
```

```sh [pnpm]
pnpm add css-loader style-loader -D
```

```sh [bun]
bun add css-loader style-loader -D
```

```sh [deno]
deno add npm:css-loader npm:style-loader -D
```

- 添加配置：

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ['style-loader', 'css-loader'],
        type: 'javascript/auto',
      },
    ],
  },
};
```

:::tip
style-loader 不能与 `type: 'css'`、`type: 'css/auto'`、`type: 'css/global'` 或 `type: 'css/module'` 同时使用，因为 css-loader 会将 css 转换成 javascript 类型。
:::

## CSS Modules

[CSS Modules](https://github.com/css-modules/css-modules) 是一种 CSS 文件的组织方式，它通过为类名自动生成唯一标识符，来局部化 CSS 的作用域，这允许你在不同的文件中使用相同的类名，而不用担心冲突。

### 内置支持

在开启 [内置 CSS 支持](#内置-css-支持) 后，Rspack 默认将扩展名为 `*.module.css` 的文件视为 CSS Modules，你可以在 JavaScript 文件中导入它，然后将 CSS 文件中定义的每个类作为模块的导出来访问。

```css title="index.module.css"
.red {
  color: red;
}
```

你可以使用命名空间导入：

```ts title="index.js"
import * as styles from './index.module.css';
document.getElementById('element').className = styles.red;
```

也可以使用具名导入：

```ts
import { red } from './index.module.css';
document.getElementById('element').className = red;
```

要在 Rspack 中启用默认导入方式，你需要在 Rspack 配置中将 `namedExports` 配置为 `false`。这允许你在用到 CSS Modules 时，除了命名空间导入和具名导入，也能通过默认导入整个样式模块：

```js title="rspack.config.mjs"
export default {
  module: {
    parser: {
      'css/auto': {
        namedExports: false,
      },
    },
  },
};
```

现在你可以使用默认导入：

```js
import styles from './index.module.css';
document.getElementById('element').className = styles.red;
```

:::tip

Rspack 提供了选项，允许你自定义 CSS Modules 的解析和生成方式：

- 解析器选项：
  - [module.parser\["css/auto"\]](https://rspack.rs/zh/config/module-parser.md#cssauto)
  - [module.parser\["css/global"\]](https://rspack.rs/zh/config/module-parser.md#cssglobal)
  - [module.parser\["css/module"\]](https://rspack.rs/zh/config/module-parser.md#cssmodule)
- 生成器选项：
  - [module.generator\["css/auto"\]](https://rspack.rs/zh/config/module-generator.md#cssauto)
  - [module.generator\["css/global"\]](https://rspack.rs/zh/config/module-generator.md#cssglobal)
  - [module.generator\["css/module"\]](https://rspack.rs/zh/config/module-generator.md#cssmodule)

:::

### 使用 css-loader

如果你没有开启 Rspack 的内置 CSS 支持，那么可以使用 [css-loader](https://github.com/webpack/css-loader) 来提供对 CSS Modules 的支持。

通过 `css-loader` 的 `modules` 选项开启：

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/i,
        loader: 'css-loader',
        type: 'javascript/auto',
        options: {
          modules: true,
        },
      },
    ],
  },
};
```

更多用法请参考 [css-loader - modules](https://github.com/webpack/css-loader#modules)。

## PostCSS

Rspack 支持使用 [postcss-loader](https://github.com/webpack/postcss-loader)，你可以这样配置：


```sh [npm]
npm add postcss postcss-loader -D
```

```sh [yarn]
yarn add postcss postcss-loader -D
```

```sh [pnpm]
pnpm add postcss postcss-loader -D
```

```sh [bun]
bun add postcss postcss-loader -D
```

```sh [deno]
deno add npm:postcss npm:postcss-loader -D
```

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: {
                // ...
              },
            },
          },
        ],
        // 如果你需要将 '*.module.css' 视为 CSS Modules 那么将 'type' 设置为 'css/auto' 否则设置为 'css'
        type: 'css/auto',
      },
    ],
  },
};
```

上述配置会将所有 `*.css` 文件经过 [postcss-loader](https://github.com/webpack/postcss-loader) 处理，并将生成的结果交给 Rspack 完成 CSS 后续流程的处理。

## Sass

Rspack 支持使用 [sass-loader](https://github.com/webpack/sass-loader)，你可以这样配置：


```sh [npm]
npm add sass-embedded sass-loader -D
```

```sh [yarn]
yarn add sass-embedded sass-loader -D
```

```sh [pnpm]
pnpm add sass-embedded sass-loader -D
```

```sh [bun]
bun add sass-embedded sass-loader -D
```

```sh [deno]
deno add npm:sass-embedded npm:sass-loader -D
```

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.(sass|scss)$/,
        use: [
          {
            loader: 'sass-loader',
            options: {
              // 同时使用 `modern-compiler` 和 `sass-embedded` 可以显著提升构建性能
              // 需要 `sass-loader >= 14.2.1`
              api: 'modern-compiler',
              implementation: require.resolve('sass-embedded'),
            },
          },
        ],
        // 如果你需要将 '*.module.(sass|scss)' 视为 CSS Modules 那么将 'type' 设置为 'css/auto' 否则设置为 'css'
        type: 'css/auto',
      },
    ],
  },
};
```

上述配置会将所有 `*.sass` 和 `*.scss` 文件经过 [sass-loader](https://github.com/webpack/sass-loader) 处理，并将生成的结果交给 Rspack 完成 CSS 后续流程的处理。

## Less

Rspack 支持使用 [less-loader](https://github.com/webpack/less-loader)，你可以这样配置：


```sh [npm]
npm add less less-loader -D
```

```sh [yarn]
yarn add less less-loader -D
```

```sh [pnpm]
pnpm add less less-loader -D
```

```sh [bun]
bun add less less-loader -D
```

```sh [deno]
deno add npm:less npm:less-loader -D
```

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        test: /\.less$/,
        use: [
          {
            loader: 'less-loader',
            options: {
              // ...
            },
          },
        ],
        // 如果你需要将 '*.module.less' 视为 CSS Modules 那么将 'type' 设置为 'css/auto' 否则设置为 'css'
        type: 'css/auto',
      },
    ],
  },
};
```

上述配置会将所有 `*.less` 文件经过 [less-loader](https://github.com/webpack/less-loader) 处理，并将生成的结果交给 Rspack 完成 CSS 后续流程的处理。

## Tailwind CSS

[Tailwind CSS](https://tailwindcss.com/) 是一个以 Utility Class 为基础的 CSS 框架和设计系统，可以快速地为组件添加常用样式，同时支持主题样式的灵活扩展。

Tailwind CSS 官网提供了集成 Rspack 的指南，请参考：

- [Install Tailwind CSS v4 with Rspack](https://tailwindcss.com/docs/installation/framework-guides/rspack/react)
- [Install Tailwind CSS v3 with Rspack](https://v3.tailwindcss.com/docs/guides/rspack)