Sass 插件#

使用 Sass 作为 CSS 预处理器，基于 sass-loader 实现。

快速开始#

安装插件#

你可以通过如下的命令安装插件:

npm add @rsbuild/plugin-sass -D

注册插件#

你可以在 rsbuild.config.ts 文件中注册插件：

import { pluginSass } from '@rsbuild/plugin-sass';

export default {
  plugins: [pluginSass()],
};

注册插件后，你可以在代码中引入 *.scss，*.sass，*.module.scss 或 *.module.sass 文件，无须添加其他配置。

选项#

如果你需要自定义 Sass 的编译行为，可以使用以下配置项。

sassLoaderOptions#

修改 sass-loader 的配置。

• 类型： Object | Function
• 默认值：

const defaultOptions = {
  api: 'modern-compiler',
  implementation: require.resolve('sass-embedded'),
  sourceMap: rsbuildConfig.output.sourceMap.css,
};

• 示例：

当 sassLoaderOptions 的值是一个对象时，它会与默认配置通过 Object.assign 进行浅层合并，值得注意的是，sassOptions 会通过 deepMerge 进行深层合并。

pluginSass({
  sassLoaderOptions: {
    sourceMap: true,
  },
});

当 sassLoaderOptions 的值是一个函数时，默认配置作为第一个参数传入，你可以直接修改配置对象，也可以返回一个值作为最终结果：

pluginSass({
  sassLoaderOptions(config) {
    config.additionalData = async (content, loaderContext) => {
      // ...
    };
  },
});

exclude#

• 类型： RuleSetCondition
• 默认值： undefined

用于排除一部分 .sass 或 .scss 模块，这些模块不会被 sass-loader 编译。

比如：

pluginSass({
  exclude: /some-folder[\\/]foo\.scss/,
});

修改 Sass 版本#

在某些场景下，如果你需要使用特定的 Sass 版本，而不是使用 Rsbuild 内置的 Sass embedded，可以在项目中安装需要使用的 Sass 版本，并通过 sass-loader 的 implementation 选项设置。

pluginSass({
  sassLoaderOptions: {
    implementation: require.resolve('sass'),
  },
});

Rsbuild 默认使用最新的 modern-compiler API，如果你使用的 Sass 版本较低，请将 sass-loader 的 api 选项设置为 legacy，以避免版本不匹配导致的异常。

pluginSass({
  sassLoaderOptions: {
    api: 'legacy',
    implementation: require.resolve('sass'),
  },
});