• 简体中文

      • 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
      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,
      },
    },
  },
};