commitlint 配置完全指南从配置文件到 Parser Preset 的深度解析【免费下载链接】commitlint Lint commit messages项目地址: https://gitcode.com/gh_mirrors/co/commitlintcommitlint 通过一套统一的配置对象驱动提交信息校验无论是规则、解析器预设、格式化器还是交互式提交提示全部集中在这份配置中。本篇指南以 docs/reference/configuration.md 为骨架结合commitlint/load、commitlint/resolve-extends、commitlint/is-ignored等核心包的源码实现系统讲解配置文件的位置与解析机制、完整配置对象各字段的语义与默认值、可共享配置的扩展原理以及 parser preset 与parserOpts的底层工作方式帮助读者从会用配置进阶到理解配置为何如此工作。配置文件从哪来文件、package.json与 CLI 三种入口通过文件配置commitlint/cli会在项目中按优先级从以下文件位置查找配置依次尝试找到即停.commitlintrc.commitlintrc.json.commitlintrc.yaml.commitlintrc.yml.commitlintrc.js.commitlintrc.cjs.commitlintrc.mjs.commitlintrc.ts.commitlintrc.cts.commitlintrc.mtscommitlint.config.jscommitlint.config.cjscommitlint.config.mjscommitlint.config.tscommitlint.config.ctscommitlint.config.mts配置文件的期望是包含合法的 JavaScript / TypeScript 代码导出一个配置对象遵循下文描述的配置结构Schema。[!NOTE] 配置文件解析由 cosmiconfig 完成因此所有 cosmiconfig 支持的行为如向上层目录搜索、搜索策略配置等都适用。源码佐证commitlint/load/src/utils/load-config.ts中的loadConfig函数正是用cosmiconfig(commitlint, ...)构造解析器并将上述文件名逐一登记到searchPlaces中其中.ts、.cts、.mts后缀通过cosmiconfig-typescript-loader的TypeScriptLoader加载。同时package.json与package.yaml也出现在searchPlaces列表的首位——这就是下一节通过package.json配置能够成立的底层原因。通过package.json配置在package.json或 pnpm 的package.yaml中新增一个commitlint字段字段值为一个符合下述结构的对象即可{ name: my-project, commitlint: { extends: [commitlint/config-conventional], rules: { type-enum: [2, always, [feat, fix, docs]] } } }这种方式适合不想单独维护配置文件、配置又比较简单的场景。通过 CLI 选项指定配置文件在命令行中通过--config或-g显式传入配置文件的路径commitlint --config commitlint.config.js该路径可以是相对当前工作目录的路径也可以是绝对路径。源码佐证commitlint/load/src/load.ts中loadConfig(cwd, options.file)会将传入的file通过path.resolve(cwd, configPath)转为绝对路径并改用explorer.load直接加载指定文件而不是explorer.search去逐级搜索。commitlint/load/src/load.test.ts中rules should be loaded from relative config file与rules should be loaded from absolute config file两个用例分别验证了相对路径与绝对路径两种加载方式fixture 位于 commitlint/load/fixtures/specify-config-file。配置对象全景一个字段一个字段讲透下面是一份覆盖全部顶层字段的完整配置示例随后逐项拆解const Configuration { /* * 从 node_modules 中解析并加载 commitlint/config-conventional。 * 引用的包必须已安装 */ extends: [commitlint/config-conventional], /* * 从 node_modules 中解析并加载 conventional-changelog-atom。 * 引用的包必须已安装 */ parserPreset: conventional-changelog-atom, /* * 从 node_modules 中解析并加载 commitlint/format。 * 引用的包必须已安装 */ formatter: commitlint/format, /* * 此处定义的任何规则都会覆盖来自 commitlint/config-conventional 的规则 */ rules: { type-enum: [2, always, [foo]], }, /* * 函数数组每个函数返回 true 表示 commitlint 应忽略该提交消息。 * 该数组会与预置的忽略函数合并预置匹配器包括 * * - Merge pull request、Merge X into Y 或 Merge branch X * - Revert X * - v1.2.3即 semver 匹配器 * - Automatic merge X 或 Auto-merged X into Y * * 完整列表见 commitlint/is-ignored/src/defaults.ts。 * 若要禁用这些默认忽略规则、让规则始终生效将 defaultIgnores 设为 false。 */ ignores: [(commit) commit ], /* * commitlint 是否使用上述默认忽略规则 */ defaultIgnores: true, /* * 校验失败时展示的自定义 URL */ helpUrl: https://github.com/conventional-changelog/commitlint/#what-is-commitlint, /* * 自定义交互式提交prompt配置 */ prompt: { messages: {}, questions: { type: { description: please input type:, }, }, }, }; export default Configuration;[!NOTE] 同时支持 CJS 格式module.exports Configuration;extends继承其他配置extends接受一个可被 Node 模块解析算法解析的 id 列表字符串或字符串数组含义是继承目标配置中的全部字段再用当前配置覆盖。已安装的 npm 包和本地文件都可用。解析规则见 commitlint/resolve-extends/src/index.ts 的getId裸名如lerna会被加上commitlint-config-前缀最终解析为commitlint-config-lernascoped 包如commitlint/config-conventional不加前缀以.开头的相对路径或绝对路径按文件处理。扩展是递归且深度合并的被扩展配置自身还可以继续extends最终结果按父配置在前、子配置在后的顺序合并后者的同名规则与字段覆盖前者。mergeWith在合并时对plugins数组采取拼接策略而非覆盖这是插件可以跨配置累积的原因。parserPreset解析器预设控制提交消息如何被拆解为 type、scope、subject、body、footer 等组成部分。默认情况下 commitlint不内置parser preset回退到conventional-changelog-angular的默认行为当extends了commitlint/config-conventional时会应用conventional-changelog-conventionalcommits预设遵循 Conventional Commits 规范。详见下文Parser Preset 专题。formatter输出格式化器formatter指定输出校验问题的模块使用 Node 模块解析算法可解析的 idexport default { formatter: commitlint/format, };源码佐证load.ts中若最终配置里没有formatter或它不是字符串会默认回退为commitlint/format而resolveFormatter会把以.开头的相对路径如./my-formatter.js相对配置文件所在目录解析为绝对路径包名与绝对路径则原样保留、交由运行时模块解析。commitlint/cli/fixtures/custom-formatter与commitlint/load/fixtures/formatter-local-module中提供了本地 formatter 的完整示例。rules规则配置规则以规则名: [级别, 条件, 值]的三元组或二元组形式声明级别level0关闭该规则1为警告warning不阻断2为错误error阻断提交。见 commitlint/config-validator/src/commitlint.schema.json 中的enum: [0, 1, 2]条件applicablealways或nevernever表示反转规则语义值value该规则的具体参数如type-enum的允许类型数组、header-max-length的长度上限。源码佐证规则三元组的合法性校验发生在 commitlint/lint/src/lint.ts 中——它逐条检查 level 是否为 0~2 的数字、条件是否为always/never、数组长度是否为 2 或 3任何不合规都会抛出带明确错误信息的异常level 为 0 的规则在真正执行时会被直接过滤跳过。规则本身可写成[2, always, [...]]静态三元组也可以写成返回三元组的函数含 async 函数与返回 Promise 的函数commitlint/load/src/load.test.ts的rules should be loaded from local用例覆盖了这四种形态。完整的规则清单参见 Rules 参考文档。ignores与defaultIgnores控制哪些提交被跳过ignores是一个函数数组每个函数接收完整提交消息、返回true表示这条消息不校验。该数组会与默认忽略匹配器合并。默认匹配器完整列表见 commitlint/is-ignored/src/defaults.ts包括Merge pull request ...、Merge ... into ...、Merge branch ...、Merge tag ...Revert .../Reapply ...amend!/fixup!/squash!语义化版本号如v1.2.3会剥离chore:前缀与[skip ci]/(skip ci)标记后判断Merged ...、Merge remote-tracking branch ...Automatic merge ...、Auto-merged ... into ...设置defaultIgnores: false可完全关闭这些默认匹配器让规则对一切消息生效。源码佐证commitlint/is-ignored/src/is-ignored.ts 中const base opts.defaults false ? [] : wildcards随后把base与用户ignores拼接后some(...)判断——任何一个匹配器返回 true 即跳过。校验时对消息先做trimEnd()仅去除 git 留下的尾部换行再传给匹配器。commitlint/lint/src/lint.ts在进入规则执行前调用isIgnored命中则直接返回valid: true。仓库提供了对应的 fixture 配置ignores、ignores-exact、default-ignores-false。helpUrl失败时展示的自定义链接helpUrl为字符串用于在提交校验失败时输出自定义帮助链接。若未配置load.ts会回退到默认 URLhttps://github.com/conventional-changelog/commitlint/#what-is-commitlintextends得到的配置优先于当前配置中的值。prompt交互式提交配置prompt对象用于配置命令行交互式提交与commitlint/cz-commitlint配合使用包括messages与questions两部分。完整配置方式参见 Prompt Config 参考文档。load.ts仅在extended.prompt是纯对象时才保留否则回退为空对象。commitlint/config-conventional自带了一套完整的英文 prompt 提示type 的枚举、emoji 与描述可以作为自定义时的参考范本见 commitlint/config-conventional/src/index.ts。TypeScript 配置获得类型提示与枚举校验配置也可以写成 TypeScript 文件。相关类型与枚举从commitlint/types导入与普通 JS 配置的主要差异如下import type { UserConfig } from commitlint/types; // [!code focus] import { RuleConfigSeverity } from commitlint/types; // [!code focus] const Configuration: UserConfig { // [!code focus] extends: [commitlint/config-conventional], parserPreset: conventional-changelog-atom, formatter: commitlint/format, rules: { type-enum: [RuleConfigSeverity.Error, always, [foo]], // [!code focus] }, // ... }; export default Configuration;要点UserConfig类型定义了配置对象的完整结构见 commitlint/types/src/load.ts写配置时能获得 IDE 自动补全与类型检查规则级别用RuleConfigSeverity枚举代替魔法数字RuleConfigSeverity.Disabled0、RuleConfigSeverity.Warning1、RuleConfigSeverity.Error2避免手写数字出错配置文件.ts/.cts/.mts由cosmiconfig-typescript-loader加载仓库 fixture 中 recursive-extends-ts 提供了 TS 配置配合 extends 递归加载的完整示例。Shareable Configuration可共享配置与extends实战任何 commitlint 配置都可以扩展其他 commitlint 配置。通过.extends键指定要扩展的配置 id这些 id 由 Node 解析算法解析因此已安装的 npm 包与本地文件都可以使用。扩展 npm 包npm install --save-dev commitlint-config-lerna commitlint/config-conventionalexport default { extends: [ lerna // 会被自动加上 commitlint-config- 前缀 commitlint/config-conventional // scoped 包不加前缀 ] }扩展本地文件export default { extends: [./commitlint.base.js, ./commitlint.types.js], };// 会被 commitlint.config.js 拾取 export default { rules: { type-enum: [2, always, [foo]], }, };// 会被 commitlint.config.js 拾取 export default { extends: [commitlint/config-conventional], // extends 可以嵌套 parserPreset: conventional-changelog-atom, };源码佐证resolveExtends的loadExtends会先解析每个 extends id递归加载其自身的 extends然后按顺序把所有配置压栈合并resolve-extends/src/index.ts。解析失败时还会尝试一个 legacy 前缀conventional-changelog-lint-config-并输出迁移警告。若最终仍找不到模块会抛出MODULE_NOT_FOUND错误——因此文档反复强调引用的包必须已安装。更多关于可共享配置的设计思路参见 Concepts – shareable config 章节。Parser Preset 专题控制提交消息的拆解方式parser preset 决定一条提交消息如何被解析成 type、scope、subject、body、footer 等组成部分。commitlint 默认不内置 parser preset回退到conventional-changelog-angular的默认解析扩展commitlint/config-conventional后则应用conventional-changelog-conventionalcommits预设遵循 Conventional Commits 规范。parserPreset属性支持三种形态字符串引用 npm 包或本地文件通过 Node 模块解析对象带parserOpts属性的内联配置内部函数加载后的模块若导出工厂函数由loadParserOpts调用其parserOpts(callback)工厂形态生成配置。使用 npm 包npm install --save-dev conventional-changelog-atomexport default { parserPreset: conventional-changelog-atom, };使用本地文件export default { parserPreset: ./parser-preset, };export default { parserOpts: { headerPattern: /^(\w*)\((\w*)\)-(\w*)\s(.*)$/, headerCorrespondence: [type, scope, ticket, subject], }, };内联parserOpts不需要单独文件时可以直接在配置对象里传parserOpts适合做小调整比如自定义 issue 前缀export default { parserPreset: { parserOpts: { issuePrefixes: [PROJ-, JIRA-], }, }, };常用parserOpts一览解析由conventional-commits-parser驱动常用选项如下选项说明headerPattern匹配提交头type、scope、subject的正则headerCorrespondence与headerPattern捕获组一一对应的字段名数组issuePrefixes匹配 issue 引用的前缀如[#, PROJ-]noteKeywords标记 footer 注释的关键字如[BREAKING CHANGE]breakingHeaderPattern检测头部破坏性变更的正则如!标记完整选项列表见conventional-commits-parser文档。源码佐证loadParserOptscommitlint/load/src/utils/load-parser-opts.ts对解析到的 preset 做了多层规整若parserOpts本身是对象则等待并解包嵌套结构保留用户在外层合并的issuePrefixes等属性见#4640修复若 preset 名称以conventional-changelog-开头且parserOpts是工厂函数则调用其回调形式提取 opts。commitlint/load/fixtures/parser-preset-partial-user-override展示了扩展配置提供headerPattern、用户仅覆盖issuePrefixes的部分覆盖场景扩展配置的完整解析链见 commitlint/load/fixtures/parser-preset-override。presetConfig精细化调整 preset 行为当使用conventional-changelog-conventionalcommits这类预设时可以传入presetConfig对象来定制预设行为而无需替换整个解析器配置。它常用于设置生成 changelog 时展示的 commit 类型export default { parserPreset: { name: conventional-changelog-conventionalcommits, presetConfig: { types: [ { type: feat, section: Features }, { type: fix, section: Bug Fixes }, { type: docs, section: Documentation, hidden: false }, { type: chore, hidden: true }, ], }, }, };presetConfig中每个条目通过section指定该类型在 changelog 中的分组标题hidden: true表示该类型不进入 changelog。可用的presetConfig选项取决于所用 preset详见conventional-changelog-conventionalcommits文档。与 semantic-release 共享同一 preset如果项目使用 semantic-release可以让 commitlint 与 semantic-release 共享同一个conventional-changelog-conventionalcommitspreset。保持两边的parserOpts与presetConfig一致可以确保 lint 阶段解析的提交结构与 semantic-release 用于版本判定和 changelog 生成时的一致export default { extends: [commitlint/config-conventional], parserPreset: { name: conventional-changelog-conventionalcommits, presetConfig: { types: [ { type: feat, section: Features }, { type: fix, section: Bug Fixes }, { type: docs, section: Documentation, hidden: false }, ], }, }, };export default { plugins: [ [ semantic-release/commit-analyzer, { preset: conventionalcommits, presetConfig: { types: [ { type: feat, section: Features }, { type: fix, section: Bug Fixes }, { type: docs, section: Documentation, hidden: false }, ], }, }, ], [ semantic-release/release-notes-generator, { preset: conventionalcommits, presetConfig: { types: [ { type: feat, section: Features }, { type: fix, section: Bug Fixes }, { type: docs, section: Documentation, hidden: false }, ], }, }, ], ], };Formatter、Rules 与 Prompt三大能力入口速查Formatter通过formatter字段指定输出格式化模块默认commitlint/format本地相对路径会相对配置文件目录解析详见上文。Rulesrules字段声明全部校验规则完整规则清单见 Rules 参考文档规则三元组的取值约束见上文rules规则配置一节。Promptprompt字段配置命令行交互式提交与commitlint/cz-commitlint配合工作完整说明见 Prompt Config 参考文档。配置加载的完整链路将上述内容串联起来一条配置从磁盘到生效的完整链路是commitlint/cli触发load()commitlint/load/src/load.tsloadConfig用 cosmiconfig 在 cwd 搜索配置文件或加载--config指定文件支持 JS/TS 各后缀与package.json的commitlint字段加载的配置对象经过 JSON Schema 校验commitlint/config-validator/src/commitlint.schema.json不合规直接抛错字符串parserPreset先被解析为{ name, path, parserOpts }对象resolveExtends递归解析并合并全部extends配置含conventional-changelog-lint-config-*legacy 回退与全局/npx 缓存查找归一化formatter缺失时回退commitlint/format、helpUrl缺失时回退默认链接、prompt非纯对象回退空对象加载插件、将函数形态的规则执行求值executeRule得到QualifiedConfiglint 阶段使用该配置的ignores/defaultIgnores判断是否跳过再按parserPreset解析消息逐条执行 level 0 的规则并汇总 errors/warnings。仓库在 commitlint/load/fixtures 与 commitlint/cli/fixtures 下提供了大量覆盖各种配置组合的测试 fixture如递归 extends、extends 携带插件、TS 配置、指定配置文件路径、默认忽略开关等是深入理解各字段边界行为的绝佳阅读材料。【免费下载链接】commitlint Lint commit messages项目地址: https://gitcode.com/gh_mirrors/co/commitlint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考