Razzle 中的 LESS 集成：razzle-plugin-less 插件从安装配置到源码原理全解析-平芜编程栈

前端
构建工具
前端构建
后端

【免费下载链接】razzle

✨ Create server-rendered universal JavaScript applications with no configuration

项目地址：https://gitcode.com/gh_mirrors/ra/razzle

razzle-plugin-less 是 Razzle 官方提供的 LESS 样式插件，让基于 Razzle 的通用（同构）JavaScript 应用可以零配置直接使用.less文件。本文将围绕该插件的完整使用手册（packages/razzle-plugin-less/README.md），结合其源码实现、单元测试与官方示例，讲解安装步骤、全部可配置项、底层 webpack loader 链以及版本演进历程，读完后你既能开箱即用地接入 LESS，也能理解插件内部的工作机制，便于按需二次定制。

插件定位与工作原理

Razzle 的核心理念是"零配置构建服务端渲染的通用 JavaScript 应用"，但 CSS 预处理器并不在其默认 webpack 配置中。razzle-plugin-less 正是为此而生：它通过 Razzle 的插件机制，在modifyWebpackConfig阶段向客户端与服务端两份 webpack 配置中追加一条针对/\.less$/的模块规则，从而把 LESS 文件的编译管线挂载进构建流程。

从 index.js 的实现可以看到，插件本质上做两件事：

拼装默认 loader 链：按style-loader → css-loader → postcss-loader → resolve-url-loader → less-loader（开发环境）或MiniCssExtractPlugin.loader → css-loader → postcss-loader → resolve-url-loader → less-loader（生产环境）的顺序组织use数组；
区分服务端与客户端：当opts.env.target !== 'web'（即服务端渲染目标）时，跳过 style-loader 与 MiniCssExtractPlugin，仅保留css-loader（并注入modules.exportOnlyLocals: true）、resolve-url-loader、postcss-loader 和 less-loader，因为服务端只需要提取样式类的局部标识符（local identifiers）用于 SSR 渲染，而不需要产出真实 CSS 文件。

值得注意的一点：服务端规则对 css-loader 的选项使用了deepmerge递归合并（见 index.js），而整体选项合并则使用浅拷贝Object.assign，这两处合并策略的差异直接决定了哪些配置可以"深度覆盖"、哪些只能整体替换，下文会详细展开。

安装与快速上手

安装依赖

插件自身需要以开发依赖安装，同时 LESS 编译器less是其 peerDependency（版本要求^4.1.0，见 package.json），需要一并安装：

yarn add razzle-plugin-less --dev yarn add less --dev

使用 npm 时等价于：

npm install razzle-plugin-less less --save-dev

默认配置接入

在项目根目录的razzle.config.js中把插件名加入plugins数组即可：

// razzle.config.js module.exports = { plugins: ['less'], };

这是官方 with-less 示例的完整配置，接入后就可以直接在源码里书写 LESS：

// src/App.less @import (css) url('https://fonts.googleapis.com/css?family=Open+Sans'); @import './other'; body { margin: 0; padding: 0; font-family: 'Open Sans', sans-serif; }

示例中同时展示了 LESS 的两种导入能力：通过@import (css)透传外部 URL 样式，以及通过@import './other'导入本地 LESS 片段（完整示例见 examples/with-less/src/App.less）。由于 less-loader 的默认配置中includePaths指向了node_modules，你甚至可以像导入普通模块一样@import '~some-package/styles.less'引入第三方样式。

自定义配置：逐项详解

当默认行为不满足需求时，可以把插件写成对象形式传入name与options：

// razzle.config.js module.exports = { plugins: [ { name: 'less', options: { postcss: { dev: { sourceMap: false, }, }, }, }, ], };

合并语义（务必先读）

插件使用Object.assign({}, defaultOptions, opts.options.pluginOptions)进行浅合并（见 index.js），因此：

自定义选项会覆盖默认选项的对应顶层键（如postcss、less、css）；
数组不会被扩展或拼接——例如postcss.plugins一旦由你自定义，就会整体替换默认的 PostCSS 插件列表，而不是追加；
每个顶层配置内部的dev/prod分支分别对应开发与生产环境，未覆盖的分支键仍保留默认值。

postcss

默认值如下（与 README 记录一致）：

{ dev: { sourceMap: true, ident: 'postcss', }, prod: { sourceMap: false, ident: 'postcss', }, plugins: [ PostCssFlexBugFixes, autoprefixer({ browsers: ['>1%', 'last 4 versions', 'Firefox ESR', 'not ie < 9'], flexbox: 'no-2009', }), ], }

通过dev/prod分别为开发、生产环境配置 PostCSS 处理参数。需要指出的是，源码中的实际默认值与 README 略有出入，应以源码为准：

生产环境的sourceMap实际取自razzleOptions.enableSourceMaps（index.js），即跟随 Razzle 全局的 source map 开关；
autoprefixer 的浏览器范围实际使用overrideBrowserslist键，并优先读取razzleOptions.browserslist，缺省时才回退到['>1%', 'last 4 versions', 'Firefox ESR', 'not ie < 9']（index.js）。这意味着在 Razzle 配置里统一声明 browserslist，即可让 LESS 管线的 autoprefixer 与项目其他部分的浏览器目标保持一致；
插件会调用postcssLoadConfig.sync()检测项目根目录是否存在独立的 PostCSS 配置文件（如postcss.config.js）。若存在，则 postcss-loader 不注入默认的postcssOptions，把控制权完全交给项目自身配置（index.js）。

ident字段用于 webpack 4 下在多个 loader 之间区分不同的 postcss-loader 实例；webpack 5 用户可忽略。

less

默认值：

{ dev: { sourceMap: true, includePaths: [paths.appNodeModules], }, prod: { sourceMap: false, includePaths: [paths.appNodeModules], }, }

includePaths由razzle/config/paths提供，指向应用的node_modules目录，这就是@import '~package/...'能够工作的原因。再次注意源码差异：生产环境的sourceMap在源码中被硬编码为true，并附注释说明——source map 是 resolve-url-loader 正常工作的前提，若不需要 source map 请在此后置阶段再关闭（index.js）。

css

默认值：

{ dev: { sourceMap: true, importLoaders: 1, modules: false, }, prod: { sourceMap: false, importLoaders: 1, modules: false, minimize: true, }, }

importLoaders: 1表示 css-loader 解析@import时回溯一个 loader（此处为 postcss-loader）。源码中的实际默认值更激进：modules并非false，而是{ auto: true, localIdentName: '[name]__[local]___[hash:base64:5]' }（index.js）。auto: true意味着只有文件名以.module.less结尾的样式才会启用 CSS Modules，普通.less文件不受影响——这是更贴合现代开发习惯的"按需模块化"策略。若你的项目依赖 README 中描述的全局样式语义，可显式将modules覆盖为false。

style

默认值为空对象{}。style-loader 仅用于开发环境的客户端构建，负责把 CSS 通过<style>标签动态注入页面以实现热更新；生产环境则被MiniCssExtractPlugin.loader替代，将样式抽离为独立 CSS 文件（测试用例同样验证了这一点，见 tests/index.test.js）。

resolveUrl

默认值：

{ dev: {}, prod: {}, }

resolve-url-loader 负责重写 CSS 中的相对url()路径，使其相对于源 LESS 文件解析。它位于 less-loader 之后、css-loader 之前，且依赖 less-loader 输出的 source map 才能精确定位资源——这正是上文提到生产环境 source map 不能随意关闭的原因。如无特殊需要，保持默认空配置即可。

源码级深入：loader 链与构建目标差异

将上述各 loader 按构建目标与环境组合，可以得到插件的完整处理管线：

构建目标	环境	loader 链（从前到后）
web（客户端）	dev	style-loader → css-loader → postcss-loader → resolve-url-loader → less-loader
web（客户端）	prod	MiniCssExtractPlugin.loader → css-loader → postcss-loader → resolve-url-loader → less-loader
node（服务端）	任意	css-loader（`exportOnlyLocals: true`）→ resolve-url-loader → postcss-loader → less-loader

其中服务端场景通过merge(options.css[constantEnv], { modules: { exportOnlyLocals: true } })深度合并（index.js），让 css-loader 只导出模块的 locals 映射而不产出样式字符串。这样在服务端渲染 React 组件时，import styles from './App.module.less'依然能拿到类名映射，配合styled-components等库的 SSR 能力实现样式一致的同构渲染。

插件还导出了一组由razzle-dev-utils/makeLoaderFinder生成的 loader 查找器（helpers.js），供自定义插件或测试代码精确定位配置中的某个 loader。

测试验证

插件的核心行为由 tests/index.test.js 覆盖。它通过createRazzleTestConfig分别生成web/dev、web/prod、node/prod三种配置，并断言：

开发环境 web 配置必须包含 style-loader、css-loader、postcss-loader、resolve-url-loader、less-loader 全部五个 loader；
生产环境 web 配置不得包含style-loader（改用 MiniCssExtractPlugin.loader），其余四个 loader 必须存在；
服务端 node 配置同样不得包含style-loader，其余 loader 必须存在。

这套测试直接对应了上文的 loader 链矩阵，是理解插件行为最直观的"可执行文档"。

版本演进与变更要点

从 CHANGELOG.md 可以看到插件近期的演进脉络：

4.2.18：支持type: module的razzle.config.js，即当项目以 ESM 方式声明模块类型时，插件可被正确加载；同时随 razzle、razzle-dev-utils 同步升级；
4.2.17：移除文件中并未使用的jest与chalk依赖，精简依赖体积；并引入 changesets 发布工作流；
4.2.16：开始使用 changesets 管理版本与变更日志。

这些改动印证了插件始终与 Razzle 主包保持同版本号同步发布（当前版本 4.2.18），且依赖管理持续收紧。如果你正在升级 Razzle，请将 razzle-plugin-less 一并升级到相同版本。

常见问题与注意事项

自定义 postcss.plugins 会整体覆盖默认插件：默认的 autoprefixer 与 flexbox 兼容修复会消失，需要你在自定义列表中自行引入，避免丢失浏览器前缀处理。
browserslist 优先级：在razzle.config.js或package.json中声明browserslist后，插件的 autoprefixer 会优先采用，无需再单独配置。
不要随意关闭生产 source map：resolve-url-loader 依赖 less-loader 的 source map，源码中生产环境默认开启即为保证url()重写正确；如确需关闭，应在构建后置阶段处理。
服务端不注入样式：SSR 构建不会输出真实 CSS，页面样式依赖客户端构建的 CSS 文件或服务端注入方案，这是 Razzle 通用渲染的既定行为，并非缺陷。
peerDependencies 版本约束：less@^4.1.0、mini-css-extract-plugin >=0.9.0 <1.0.0、postcss@^8.2.4、style-loader@^2.0.0、webpack@~4||~5等约束（见 package.json）决定了插件的兼容边界，安装依赖时请留意版本对齐。