• 简体中文

      • tools.less

      • 类型： Object | Function
      • 默认值：
      const defaultOptions = {
  lessLoaderOptions: {
    lessOptions: {
      javascriptEnabled: true,
    },
    // 默认在开发环境下启用 CSS 的 Source Map
    sourceMap: isDev,
  },
};

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

      选项说明
      lessLoaderOptions传给 less-loader 的选项，支持对象或函数
      include指定哪些文件交给 less-loader 处理，默认 /\.less$/
      exclude指定哪些文件不交给 less-loader 处理
      parallel是否使用 worker 线程并行编译 Less，默认 false

      修改 less-loader 选项

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

      export default {
  tools: {
    less: {
      lessLoaderOptions: {
        lessOptions: {
          javascriptEnabled: false,
        },
      },
    },
  },
};

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

      export default {
  tools: {
    less: {
      lessLoaderOptions(config) {
        // 修改 lessOptions 配置
        config.lessOptions = {
          javascriptEnabled: false,
        };
      },
    },
  },
};

      并行编译

      Less 编译是纯 JavaScript 计算，默认只占用 Node.js 主线程。开启 parallel 后，Less 模块会分发到 worker 线程池中编译，项目里 Less 文件较多时可以缩短构建时间。

      export default {
  tools: {
    less: {
      parallel: true,
    },
  },
};
      Tip

      传给 worker 线程的选项需要满足结构化克隆算法的要求，因此开启 parallel 后，lessLoaderOptions 中不能包含函数，例如 additionalData 函数或自定义的 implementation。

      修改 Less 版本

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

      export default {
  tools: {
    less: {
      lessLoaderOptions: {
        implementation: require('less'),
      },
    },
  },
};

      工具函数

      addExcludes

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

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

      export default {
  tools: {
    less: {
      lessLoaderOptions(config, { addExcludes }) {
        addExcludes(/node_modules/);
      },
    },
  },
};

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

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

      兼容旧写法

      不要混写两种层级

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

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

      // 旧写法
export default {
  tools: {
    less: {
      lessOptions: { javascriptEnabled: false },
    },
  },
};

// 新写法
export default {
  tools: {
    less: {
      lessLoaderOptions: {
        lessOptions: { javascriptEnabled: false },
      },
    },
  },
};