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

# tools.sass

- **类型：** `Object | Function`
- **默认值：**

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

`tools.sass` 用于修改 [@rsbuild/plugin-sass](https://rsbuild.rs/plugins/list/plugin-sass) 的选项，取值为该插件的完整选项：

| 选项                  | 说明                                                                           |
| ------------------- | ---------------------------------------------------------------------------- |
| `sassLoaderOptions` | 传给 [sass-loader](https://github.com/webpack-contrib/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 进行深层合并。

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

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

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

### 关闭 URL 重写

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

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

### 修改 Sass 版本

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

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

### 工具函数

#### addExcludes

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

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

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

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

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

### 兼容旧写法

:::warning 不要混写两种层级
同一个对象里只要出现插件顶层键（`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`，产出的配置与之前完全一致；在开发环境下会打印一条迁移提示，并将在下一个大版本中移除。

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

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