引用 CSS 文件

引用 CSS 文件

Rsbuild 对 CSS 提供开箱即用的支持，包括 Lightning CSS、PostCSS、CSS Modules、CSS 预处理器、CSS 内联和 CSS 压缩。

Rsbuild 也提供了多个配置项，允许自定义 CSS 文件的处理规则。

Lightning CSS

TIP

Lightning CSS 是一个基于 Rust 编写的高性能 CSS 解析、转译和压缩工具。它支持将许多现代的 CSS 特性解析并转化为指定浏览器支持的语法，并提供更好的压缩比例。

Rsbuild 使用 Rspack 内置的 lightningcss-loader 来转换 CSS 代码，它会自动读取项目中的 browserslist 配置，并将 CSS 代码转换为目标浏览器支持的语法。

特性

Lightning CSS 会自动添加浏览器前缀，比如 -webkit-、-moz-、-ms- 等，因此你不需要手动添加前缀，也不需要使用 autoprefixer 插件。
Lightning CSS 会自动将 CSS 语法降级，这允许你在代码中使用现代的 CSS 特性，比如 CSS nesting，custom media queries 等，而无需担心浏览器兼容性问题。
你可以使用 tools.lightningcssLoader 来自定义 lightningcss-loader 的选项。

禁用 Lightning CSS

如果 Lightning CSS 无法满足你的需求，你也可以禁用 Lightning CSS，并使用 PostCSS 来转换 CSS 代码。

步骤如下：

将 tools.lightningcssLoader 设置为 false 来禁用 Lightning CSS loader。
使用 @rsbuild/plugin-css-minimizer 来将 CSS 压缩工具从 Lightning CSS 切换到 cssnano 或其他 CSS 压缩器。

rsbuild.config.ts

import { pluginCssMinimizer } from '@rsbuild/plugin-css-minimizer';
export default {
  plugins: [pluginCssMinimizer()],
  tools: {
    lightningcssLoader: false,
  },
};

参考使用 PostCSS，配置你需要的 PostCSS 插件，下面是一些常用的 PostCSS 插件：

autoprefixer：添加浏览器前缀。
postcss-preset-env：将现代 CSS 语法转换为大多数浏览器支持的语法。
postcss-nesting：支持 CSS nesting。

CSS 压缩

在生产模式构建时， Rsbuild 会开启 Rspack 内置的 LightningCssMinimizerRspackPlugin 插件，将 CSS 资源压缩，以达到更好的传输效率。

你可以通过 output.minify 选项来禁用 CSS 压缩，或是自定义 LightningCssMinimizerRspackPlugin 的选项。
你可以通过 @rsbuild/plugin-css-minimizer 来自定义 CSS 压缩工具，切换到 cssnano 或是其他 CSS 压缩器。

使用 PostCSS

Rsbuild 支持通过 PostCSS 来转换 CSS 代码。你可以通过以下方式来配置 PostCSS：

Rsbuild 使用 postcss-load-config 来加载当前项目根目录下的 PostCSS 配置文件，比如 postcss.config.js：

postcss.config.js

module.exports = {
  'postcss-px-to-viewport': {
    viewportWidth: 375,
  },
};

通过 Rsbuild 的 tools.postcss 选项来配置 postcss-loader，该选项支持通过函数来修改内置配置，比如：

rsbuild.config.ts

export default {
  tools: {
    postcss: (opts) => {
      const viewportPlugin = require('postcss-px-to-viewport')({
        viewportWidth: 375,
      });
      opts.postcssOptions.plugins.push(viewportPlugin);
    },
  },
};

当你同时配置 postcss.config.js 文件和 tools.postcss 选项时，两者都会生效，并且 tools.postcss 的优先级更高。
如果项目中没有 postcss.config.js 文件，也没有配置 tools.postcss 选项，Rsbuild 将不会注册 postcss-loader。

使用 CSS Modules

Rsbuild 默认支持 CSS Modules，请阅读使用 CSS Modules 章节来了解 CSS Modules 的完整用法。

使用 CSS 预处理器

Rsbuild 通过插件来支持社区流行的 CSS 预处理器，包括 Sass、Less 和 Stylus，使用方式请参考：

CSS-in-JS

请阅读 React - CSS-in-JS 章节来了解如何在 Rsbuild 中使用常见的 CSS-in-JS 库。

内联 CSS 文件

默认情况下，Rsbuild 会把 CSS 提取为独立的 .css 文件，并输出到构建产物目录。

如果你希望将样式内联到 JS 文件中，可以将 output.injectStyles 设置为 true 来禁用 CSS 提取逻辑。当浏览器请求到 JS 文件后，JS 将动态地向 HTML 插入 <style> 标签，以此加载 CSS 样式。

export default {
  output: {
    injectStyles: true,
  },
};

这将会增大你的 JS Bundle 体积，因此通常情况下，不太建议禁用 CSS 提取逻辑。

引用 node_modules 里的样式

Rsbuild 支持引用 node_modules 里的 CSS 文件。

在 JS 文件中引用：

src/index.js

/* 引用 normalize.css */
/* https://github.com/necolas/normalize.css */
import 'normalize.css';

在 CSS 文件中引用：

src/index.css

@import 'normalize.css';
body {
  /* */
}

在 Sass 和 Less 文件中，也允许添加 ~ 前缀来解析 node_modules 里的样式文件，但这是一个废弃的特性，建议从代码中移除 ~ 前缀。

src/index.scss

@import '~normalize.css';