• 前端
• 开发工具

导读

本文基于 Less.js 官方贡献指南（CONTRIBUTING.md），结合仓库内真实源码，系统梳理参与 Less.js 开源协作的完整路径：如何写出高质量 Bug 报告、如何发起特性请求、如何提交被快速合入的 Pull Request，以及 Less.js 背后"全自动"的版本发布机制（master / alpha 双通道、npm 发布与 GitHub Release）。读完你将掌握一套可直接上手操作的贡献流程，并理解这些流程在仓库代码（package.json、packages/less/Gruntfile.cjs）中的具体落地方式。

开始之前：项目形态与基础约定

Less.js 是一个 pnpm 管理的 monorepo。仓库根目录的 package.json 声明了工作区根包@less/root（当前版本 4.8.0），核心编译器位于 packages/less（npm 包名less），测试数据与插件样例则分布在 packages/test-data 等独立包中。根 package.json 中的postinstall脚本为npx only-allow pnpm，即安装依赖时强制使用 pnpm（packageManager: "pnpm@9.15.9"）。

开始贡献前，有一条必须遵守的写作约定：所有以@开头的单词必须用反引号包裹，例如写`@username`而非@username。这是为了避免在 GitHub 上意外 @ 到真实用户、触发无关通知。这一约定同样适用于 PR 描述、Issue 正文与评论。

若需在本地克隆仓库进行开发，可使用：

git clone https://gitcode.com/gh_mirrors/le/less.js cd less.js pnpm install

报告问题：让 Bug 报告一次到位

Less.js 欢迎 Bug 报告与特性请求，但遵循以下六条准则可以显著提升问题被定位和修复的效率：

1. 先搜索已有 Issue：大量问题已被报告甚至修复，先搜索能节省所有人的时间。
2. 提供隔离且可复现的最小用例：参考业界通用的"reduced test case"思路，把问题裁剪到最小可复现规模，而不是贴整个项目。
3. 先用最新版本测试：很多问题在新版本中已修复，报告前请先升级验证。
4. 附上带源码的示例：官方推荐的 Less Preview 在线工具可快速生成一段短小的测试用例，方便维护者直接复现。
5. 尽可能多地共享环境信息，至少包括：
   • 操作系统及版本；
   • Less 的使用方式（浏览器、命令行lessc、构建工具/插件等）；
   • 浏览器名称与版本（若与浏览器相关）；
   • 所用 Less.js 的版本号；
   • 可复现该问题的清晰操作步骤。
6. 如果有解决方案，直接提出来：可以在 Issue 中附上修复思路，甚至直接提交 Pull Request。

此外，Less.js 语言文档（lesscss.org 官方文档站点）由独立的文档项目维护，文档类问题请提交到文档项目仓库，而非本仓库的 Issue 区。

特性请求：先对齐需求再动手

提交特性请求时，注意三点：

• 先搜索已有的特性请求：很多功能已被规划或正在评估中，避免重复提案。
• 给出明确、具体的应用场景：说明实际需求是什么、会如何被使用，帮助维护者判断价值。
• 考虑替代方案：有时候某个函数或第三方构建系统比在语言核心中加功能更合适。

官方在文档中特别强调：对 Less.js 最有价值的贡献通常是组织性的——修复 Bug、提升代码质量、增强工具链、完善文档。语言特性本身总体保持稳定，未实现的规划功能不一定适合通过一次 PR 快速落地。

提交 Pull Request：让合入更顺畅

Pull Request 是代码贡献的主要入口，官方给出如下建议：

• 新功能先发特性请求，获得反馈后再动手，避免方向性返工；
• 如果 PR 的解法与已有 Issue 不同，先新建 Issue 与核心维护者讨论方案，避免白费精力；
• 不要提交dist/目录：该目录被 gitignore，构建产物只在发布流程中自动生成；
• 必须为改动添加测试，并运行pnpm test——该命令会同时执行 Node.js 测试与浏览器（Headless Chrome）测试。

编码规范

• 始终使用空格缩进，绝不使用 Tab；
• 语句以分号结尾；
• 以 ESLint 规范为准。

仓库中的落地情况：ESLint 基础配置位于 config/eslint/base.cjs；根 package.json 提供pnpm lint（eslint packages/less --ext .js,.ts）与pnpm lint:fix；packages/less/package.json 中亦有lint: "eslint '**/*.{ts,js}'"。在 packages/less/Gruntfile.cjs 的eslint任务中，检查范围覆盖test/**/*.js与lib/less*/**/*.js（并排除了测试用的错误插件样例），且开启了fix: true自动修复。

认领 Issue

如果你想动手解决某个 Issue，请在 Issue 下留言说明"由你接管"，这可以避免多人同时重复工作。

开发与测试体系：源码级解读

官方文档要求提交前运行pnpm test。这一命令在仓库中实际触发了一条完整的测试链，理解它有助于快速定位失败原因。

测试命令的调用链

从根 package.json 的脚本定义看：

• test: "cd packages/less && npm test"——根目录的pnpm test会进入编译器包；
• packages/less/package.json 中test: "grunt test"——进而触发 Grunt 的test任务。

而 packages/less/Gruntfile.cjs（第 347-357 行）中test任务由以下子任务串成：

clean → eslint → shell:build → shell:testbuild → shell:test → shell:opts → shell:plugin → connect → shell:runbrowser

即依次完成：清理临时产物 → ESLint 检查 → 用 Rollup 构建发布版 → 构建浏览器测试版 → 运行 Node 端测试（ESM/CJS/浏览器打包/核心套件）→ 校验各命令行选项 → 校验插件 → 启动本地静态服务 → 用 Playwright（Headless Chrome）跑浏览器测试。

常用测试命令速查

其中test:node的任务链（shell:build → shell:test → shell:testcjs → shell:opts → shell:plugin）正是 packages/less/package.json 中prepublishOnly（typecheck && grunt dist && grunt test:node）在发布前自动执行的关卡——也就是说，能发布的代码必须通过类型检查、构建与 Node 全量测试。

测试数据的组织

Less.js 的测试数据独立存放在 packages/test-data 包（@less/test-data，作为 workspace 依赖被引用）。目录结构按测试维度划分，例如tests-unit/（语言特性用例，每个特性含.less与期望.css对照）、tests-config/（命令行选项/配置场景，含styles.config.cjs描述执行方式）、tests-error/（期望报错的用例，eval/与parse/分别对应求值阶段与解析阶段错误）。提交新功能时，在对应目录补充.less用例与期望输出，并在期望报错的场景中附上.txt错误信息，即完成了"为改动添加测试"的基本动作。

浏览器测试与基准测试

• 浏览器测试：由 packages/less/test/browser/generator 生成页面，packages/less/test/mocha-playwright/runner.js 通过 Playwright（devDependencies 中playwright@1.50.1）驱动 Headless Chrome 执行，因此本地无需手工打开浏览器。
• 基准测试：grunt benchmark任务执行node benchmark/index.js，历史结果存放在 packages/less/benchmark/results，用于跟踪性能回归。

发布流程：master 与 alpha 双通道的自动化发布

Less.js 的发布完全自动化。当代码被推送到特定分支时，GitHub Actions 会自动完成：运行测试与构建 → 自动提升版本号 → 以对应 tag 发布到 npm → 创建 GitHub Release。

分支与版本策略

三种发布操作

Patch 级发布（全自动）：将 PR 合并进master即可。工作流会比较 packages/less/package.json 中的版本号与 npm 上最新版本：若前者更大则直接采用，否则自动递增到下一个小 patch 版本，随后发布到 npm 并创建带less.js、less.min.js附件的 GitHub Release。

Minor / Major 级发布：先创建发布分支（如release/v4.7.0），更新所有package.json的version字段并同步更新 CHANGELOG.md，合并回master后，工作流检测到版本领先于 npm 即直接发布。

Alpha 级发布：直接在alpha分支提交并推送，工作流自动递增 alpha 版本号并发布。

版本覆盖：EXPLICIT_VERSION

在 CI 或手动运行等场景下，可用环境变量EXPLICIT_VERSION强制指定发布版本：

EXPLICIT_VERSION=4.7.0 pnpm run publish

根 package.json 中与之对应的脚本包括publish: "node scripts/bump-and-publish.js"、publish:dry-run: "DRY_RUN=true node scripts/bump-and-publish.js"与publish:beta，可用于在本地预先演练发布流程。

发布资产

每个 GitHub Release 自动附带两个浏览器构建产物：

• less.js——完整浏览器构建；
• less.min.js——压缩后的浏览器构建。

二者在发布工作流中由 Rollup 构建（对应 packages/less/Gruntfile.cjs 中shell:build的node build/rollup.js --dist）并附加到 Release，不会提交到 git（dist/目录被 gitignore）。这一点与贡献指南中"不要提交 dist/"的要求完全一致。

安全机制

发布流程采用 npm 官方推荐的trusted publishing（OIDC 认证），这意味着：

• 无需维护长期有效的发布 token；
• 自动生成软件供应链 provenance（来源证明）；
• 使用短期、工作流专用的凭据，安全性更强。

发布工作流（文档中描述为.github/workflows/publish.yml）会同时处理正式版与 alpha 版两类发布。

发布约束速记

• 发布只会在master或alpha分支触发；
• Alpha 版本号必须包含-alpha.，且发布到alphatag；
• 正式版发布到latesttag；
• alpha分支在发布前必须与master保持同步；
• Alpha 的基础版本必须不低于 master 版本（遵循 semver 比较）。

合并 master 到 alpha：双层版本保护

频繁合并master到alpha时，package.json中的版本号可能被覆盖，Less.js 为此设置了两层保护：

1. Post-merge git hook（自动）：在pnpm install时通过 husky 自动安装（根 package.json 的prepare: "husky"脚本及husky@~9.1.7devDependency 佐证了这一点）。git merge后自动运行，若 alpha 版本被覆盖则自动恢复并递增，并提示提交恢复后的版本。

2. 发布脚本兜底检测：即使 hook 未安装，发布脚本也会兜底——在 git 历史中搜索最近一次 alpha 版本，恢复并递增（例如5.0.0-alpha.3→5.0.0-alpha.4），并同步更新所有package.json文件。

这套"hook 优先、脚本兜底"的设计，保证了双通道版本策略即使在人为合并失误时也不会被破坏。

结语

从一条规范的 Issue、一个带测试的 PR，到一次全自动的 npm 发布，Less.js 的贡献链路在文档与源码中是完全自洽的：贡献指南定义了协作规则，根 package.json 与 packages/less/package.json 定义了命令入口，packages/less/Gruntfile.cjs 定义了测试与构建流水线，发布分支策略则保证了版本演进的安全与可控。无论你是想修复一个 Bug、补一个测试用例，还是完整走一遍"提交 → 合入 → 发版"，都可以按本文的步骤直接开始。

• 前端
• 开发工具