tools.sass

类型： Object | Function
默认值：

const defaultOptions = {
  sassLoaderOptions: {
    // 默认在开发环境下启用 CSS 的 Source Map
    sourceMap: isDev,
  },
};

tools.sass 用于修改 @rsbuild/plugin-sass 的选项，取值为该插件的完整选项：

选项	说明
`sassLoaderOptions`	传给 sass-loader 的选项，支持对象或函数
`include`	指定哪些文件交给 sass-loader 处理，默认 `/\.s(?:a\|c)ss$/`
`exclude`	指定哪些文件不交给 sass-loader 处理
`rewriteUrls`	是否使用 resolve-url-loader 重写 Sass 文件中的相对 URL，默认 `true`

修改 sass-loader 选项

sassLoaderOptions 为 Object 类型时，会与默认配置通过 Object.assign 进行浅层合并，值得注意的是，sassOptions 会通过 deepMerge 进行深层合并。

export default {
  tools: {
    sass: {
      sassLoaderOptions: {
        sourceMap: true,
      },
    },
  },
};

sassLoaderOptions 为 Function 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果，第二个参数提供了一些可以直接调用的工具函数：

export default {
  tools: {
    sass: {
      sassLoaderOptions(config) {
        // 修改 additionalData 配置
        config.additionalData = async (content, loaderContext) => {
          // ...
        };
      },
    },
  },
};

关闭 URL 重写

默认情况下，Sass 文件里的相对 URL 会经过 resolve-url-loader 重写为相对于源文件的路径。如果项目不依赖这一行为，可以关闭它来减少一个 loader：

export default {
  tools: {
    sass: {
      rewriteUrls: false,
    },
  },
};

修改 Sass 版本

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

export default {
  tools: {
    sass: {
      sassLoaderOptions: {
        implementation: require('sass'),
      },
    },
  },
};

工具函数

addExcludes

类型： (excludes: RegExp | RegExp[]) => void

用来指定 sass-loader 不编译哪些文件，你可以传入一个或多个正则表达式来匹配 sass 文件的路径。例如：

export default {
  tools: {
    sass: {
      sassLoaderOptions(config, { addExcludes }) {
        addExcludes(/node_modules/);
      },
    },
  },
};

推荐直接使用插件的 exclude 选项，效果相同：

export default {
  tools: {
    sass: {
      exclude: /node_modules/,
    },
  },
};

兼容旧写法

不要混写两种层级

同一个对象里只要出现插件顶层键（sassLoaderOptions、include、exclude 等），整个对象就会按插件选项解析，其中的 loader 选项不会生效。例如 tools.sass: { rewriteUrls: false, sassOptions: { ... } } 里的 sassOptions 会被忽略，必须移到 sassLoaderOptions 下；开发环境下会打印一条提示。

在之前的版本中，tools.sass 的取值直接是 sass-loader 的选项，例如 tools.sass: { sassOptions: {} } 或 tools.sass(config, { addExcludes }) {}。这种写法目前仍然生效，Modern.js 会自动把它包装为 sassLoaderOptions，产出的配置与之前完全一致；在开发环境下会打印一条迁移提示，并将在下一个大版本中移除。

// 旧写法
export default {
  tools: {
    sass: {
      sourceMap: true,
    },
  },
};

// 新写法
export default {
  tools: {
    sass: {
      sassLoaderOptions: {
        sourceMap: true,
      },
    },
  },
};

#tools.sass

#修改 sass-loader 选项

#关闭 URL 重写

#修改 Sass 版本

#工具函数

#addExcludes