close
  • 简体中文

      • Less 插件

      源码

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

      快速开始

      安装插件

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

      npm
      yarn
      pnpm
      bun
      deno
      npm add @rsbuild/plugin-less -D
      Tip
      • Less 插件仅支持 @rsbuild/core >= 0.7.0 版本。
      • 当 @rsbuild/core 版本小于 0.7.0 时，内置支持 Less 插件，你不需要安装该插件。

      注册插件

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

      rsbuild.config.ts
      import { pluginLess } from '@rsbuild/plugin-less';

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

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

      选项

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

      lessLoaderOptions

      修改 less-loader 的配置。

      • 类型： Object | Function
      • 默认值：
      const defaultOptions = {
  lessOptions: {
    javascriptEnabled: true,
    paths: [path.join(rootPath, 'node_modules')],
  },
  implementation: require.resolve('less'),
  sourceMap: rsbuildConfig.output.sourceMap.css,
};
      • 示例：

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

      pluginLess({
  lessLoaderOptions: {
    lessOptions: {
      javascriptEnabled: false,
    },
  },
});

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

      pluginLess({
  lessLoaderOptions(config) {
    config.lessOptions = {
      javascriptEnabled: false,
    };
  },
});
      Tip

      lessLoaderOptions.lessOptions 是直接传递给 Less 的配置，请参阅 Less 文档 以了解所有可用选项。

      include

      用于指定一部分 .less 模块，这些模块会被 less-loader 编译。这个值与 Rspack 中的 rule.test 选项相同。

      比如：

      pluginLess({
  include: /\.custom\.less$/,
});

      exclude

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

      比如：

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

      parallel

      • 类型： boolean
      • 默认值： false
      • 版本： 添加于 v1.4.0

      是否开启并行 loader 执行，在 worker 线程中运行 less-loader。开启后，在编译大量 Less 模块时通常会有构建性能提升。

      注意该选项为实验性功能，当 Less 选项中包含函数时将无法正常工作。

      pluginLess({
  parallel: true,
});

      详见 Rspack - Rule.use.parallel。

      修改 Less 版本

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

      pluginLess({
  lessLoaderOptions: {
    implementation: require('less'),
  },
});

      实践

      配置多个 Less 插件

      通过使用 include 和 exclude 选项，你可以同时注册多个 Less 插件，并为每个插件指定不同的选项。

      例如：

      export default {
  plugins: [
    pluginLess({
      exclude: /\.another\.less$/,
    }),
    pluginLess({
      include: /\.another\.less$/,
      lessLoaderOptions: {
        // some custom options
      },
    }),
  ],
};

      常见问题

      Less 文件中的除法不生效？

      @rsbuild/plugin-less 内置的 Less 版本为 v4，与 v3 版本相比，除法的写法有一些区别：

      // Less v3
.math {
  width: 2px / 2; // 1px
  width: 2px ./ 2; // 1px
  width: (2px / 2); // 1px
}

// Less v4
.math {
  width: 2px / 2; // 2px / 2
  width: 2px ./ 2; // 1px
  width: (2px / 2); // 1px
}

      Less 中除法的写法可以通过配置项来修改，详见 Less - Math。