如何在Less中通过JavaScript环境注入实现自定义函数以增强编译功能？

本文共计1024个文字，预计阅读时间需要5分钟。

Less的自定义函数（functions）只能在JavaScript运行时编译阶段注册，而浏览器端加载less.js时无法动态挂载函数插件——它只支持内置函数和变量解析。真正在运行时调用自定义逻辑，必须使用Node.js的less.render或构建工具链（如Webpack/Vite插件、Gulp、Grunt）。

• 浏览器直接 <link rel="stylesheet/less"> + less.js：函数注册无效，调用会报 ReferenceError: functionName is not defined
• Node.js 调用 less.render() 时未传入 functions 配置项：函数名被当作普通变量或语法错误处理
• 使用 lessc 命令行时未指定 --functions 参数：函数调用直接失败，提示 Unrecognised input

在 less.render() 中注册函数的正确写法

Node.js 下调用 Less API 注册函数，核心是把函数对象作为 options.functions 属性传入，且函数必须返回 less.tree.Value 类型实例（不能直接 return 字符串或数字）。

• 必须引入 less 包本身，不能只靠全局 less 对象（比如 Webpack 中需 import less from 'less'）
• 函数参数是 less.tree.Node 实例，需用 .value、.unit 等属性取值；例如 args[0].value 获取第一个参数原始值
• 返回值必须包装为 new less.tree.Dimension(value, unit)（数值）、new less.tree.Color(hex)（颜色）等对应 AST 节点
• 示例：实现 px2rem(375px) → 1.953125rem

const less = require('less'); const px2remFunction = { 'px2rem': function (args) { const pxValue = parseFloat(args[0].value); const remValue = pxValue / 192; // 基准 192px = 1rem return new less.tree.Dimension(remValue, 'rem'); } }; less.render(lessCode, { functions: px2remFunction, filename: 'input.less' }).then(output => { console.log(output.css); });

构建工具中启用自定义函数的常见路径差异

不同工具对 functions 的接入方式一致，但插件初始化位置和参数结构略有区别，容易因路径或实例化时机出错。

• gulp-less：需显式 require('less-plugin-functions') 并 new 实例，再传入 plugins: [instance]；若直接传函数对象会静默失效
• grunt-contrib-less：v3.0+ 支持 options.functions 直接接收函数对象，但旧版需配合 less-plugin-functions 插件
• webpack-less-loader：通过 lessOptions.functions 传入，注意 Webpack 5+ 的 loader 配置嵌套层级较深，易漏掉 lessOptions
• 命令行 lessc：必须用 --functions path/to/fns.js，且该 JS 文件需导出一个对象（如 module.exports = { px2rem: ... }），不能是 ES Module 默认导出

函数内访问变量和作用域的限制

Less 自定义函数内部无法直接读取当前作用域的 @variable，也不能调用其他函数或触发 import；它是一个纯计算沙箱。

立即学习“Java免费学习笔记（深入）”；

• 想让函数响应主题变量变化？必须把变量值作为参数显式传入，例如 px2rem(@base-font-size, 16px)
• 函数中不能使用 @arguments、& 或选择器上下文，所有输入都来自调用时的参数列表
• 若需复用逻辑，建议在 JS 层预处理参数（比如从配置对象提取 rootFontSize），再注入函数实现
• 调试时可在函数体加 console.log，但仅在 Node.js 环境可见；浏览器端无任何输出，也不抛错，只会编译失败

Less 自定义函数不是“写个 JS 函数就能用”，它本质是 AST 节点构造器。最容易忽略的是返回值类型——漏掉 new less.tree.Dimension(...) 包装，就会导致编译中断且错误信息极不明确，比如只报 TypeError: Cannot read property 'toCSS' of undefined。