代码规范写在文档里没人看？让它跑进流水线自动卡

摘要：

代码规范写得再全，躺在文档里也常被忽略，靠人工记忆执行难免打折扣。腾讯云 CNB 支持把规范检查挂进流水线，用 commitlint、各语言 lint 插件在提交或合并前自动卡点，让规范真正落地。本文介绍如何配置。

一、规范写在文档里，为什么就是没人看

几乎每个团队都有一份代码规范文档。命名怎么起、缩进用几个空格、提交信息怎么写、文件怎么组织，一条条列得清清楚楚。可现实是，这份文档大多躺在 Wiki 或仓库根目录，真正提交代码时没几个人会逐条对照。

这不是团队不认真，而是"靠文档 + 靠自觉"的执行方式本身就有短板：

• 记不全：规范条目一多，没人能全记住，赶进度时更容易凭手感写，写完才发现某处不符合约定；
• 没人盯：文档是静态的，不会主动拦下不合规的提交，合规与否全看提交者当时有没有想起来翻一眼；
• 标准不统一：评审者自己也可能漏，不同人对同一条规范的理解还不完全一样，把关结果因人而异。

结果就是，规范写得再全，也停留在"纸上"。要让它真正落地，思路得从"写进文档让人看"变成"放进流水线自动卡"——把规范检查变成一道机器执行的关卡，提交不符合规范就过不去，用工具代替人盯人。CNB 的流水线正好能把这件事接住。

二、把规范"放进流水线"：从靠自觉到靠卡点

腾讯云云原生构建（Cloud Native Build，简称 CNB）基于 Docker 生态，用 .cnb.yml 声明式配置流水线，支持 Pipeline/Stage/Job 三层结构、PR 等多种事件触发。它的插件市场提供了一批现成的规范检查插件，覆盖提交信息、各语言代码风格、PR 标题和变更规模等维度，可以把团队规范变成流水线里自动执行的检查项。

这些插件大致分几类：

把这些插件挂到流水线的合适位置，规范就从"文档里的一行字"变成了"流水线里的一道闸"。提交或 PR 一旦触碰红线，流水线直接失败，不合规的代码就进不了主干。

三、提交信息规范：用 commitlint 卡住第一关

规范落地，第一关往往是提交信息。约定式提交（Conventional Commits）要求提交开头用 feat、fix、docs、refactor 这类类型前缀，后面跟简短说明。统一了提交格式，后续的变更日志生成、版本管理、问题追溯都会顺很多。

靠人工要求每个人记得加前缀，效果往往有限。用 CNB 的 commitlint 插件，就能把这条规范变成硬卡点。在 .cnb.yml 里挂一个检查 Stage，提交信息不符合规范时让流水线失败：

main:
  push:
    - stages:
        - name: 提交信息检查
          image: cnbcool/commitlint:latest
          # 让检查不通过时流水线失败（阻断提交），具体参数以插件详情页为准

逐行看：

• main: 表示对 main 分支生效，可按 glob 模式匹配其他分支；
• push: 表示代码推送时触发，在提交进入仓库前就把关；
• image: cnbcool/commitlint:latest 使用官方 commitlint 插件镜像；
• 插件默认在检查不通过时让流水线失败，从而卡住这次提交（具体行为参数以插件详情页为准）。

这样一来，提交信息写得随意（比如"update""修了个 bug"这种不符合约定的），流水线直接红灯，作者只能按规范重写提交信息。规范不用靠记忆，机器替你记着。

四、代码风格规范：用语言 lint 插件逐行把关

提交信息之外，更大量的是代码本身的风格规范：缩进、命名、未使用变量、潜在的空值问题等等。这类规范条目多、细节碎，人工逐行检查既不现实也容易漏。CNB 插件市场提供的语言 lint 插件，可以在流水线里对代码做风格检查。

按语言选用对应插件即可，例如：

• Go 项目用 go-lint，检查 Go 代码的风格和常见问题；
• C/C++ 项目用 cpplint，对照风格约定检查；
• Markdown 文档用 markdown-lint，检查文档格式规范；
• PHP 项目用 phplint，做语法和风格层面的检查。

配置思路和 commitlint 一致，以 Go 项目为例：

main:
  pull_request:
    - stages:
        - name: 代码风格检查
          image: cnbcool/go-lint:latest
          # 让检查不通过时流水线失败（阻断合并），具体参数以插件详情页为准

把这段挂到 PR 事件上，每次提 PR 都会自动跑一遍风格检查，不符合团队约定的写法会被指出来并阻断合并。文档里那几十条风格规范，就此从"供人翻阅"变成"供机器执行"，执行力度完全不同。

实际落地时，可以按团队使用的语言，挑选对应的 lint 插件组合进同一条流水线，让多种语言的风格检查在一次 PR 里一并完成。

五、PR 维度的规范：标题和变更规模也管起来

除了代码本身，团队往往还对 PR 的"外在"有规范：标题要不要带前缀、一次 PR 允许改多少行、commit 次数要不要限制。这类规范同样适合用插件自动卡。

PR 标题规范用 git-pr-title-lint。很多团队要求 PR 标题带上模块名或类型前缀，方便检索和归类。靠人工提醒容易漏，用插件在 PR 创建时检查标题格式，不符合约定的直接拦下：

main:
  pull_request:
    - stages:
        - name: PR 标题检查
          image: cnbcool/git-pr-title-lint:latest
          # 让检查不通过时流水线失败（阻断 PR），具体参数以插件详情页为准

PR 变更规模用 git-pr-limit。它检查单次 PR 的 commit 次数和代码变更行数，防止一次提交改动过大、难以评审。对变更量或 commit 次数超出设定阈值的 PR，插件会让流水线失败，提醒作者拆分成更小的 PR。这对保持评审质量、降低合并风险很有帮助——几百行的大 diff 往往看不动、容易漏，用 git-pr-limit 把单次变更控制在合理范围，评审和回滚都更轻松。

六、让规范真正落地的几个建议

把规范跑进流水线，配置只是第一步，落地效果还取决于怎么用。结合实践，有几条建议能让这套机制更顺：

• 先卡最该卡的环节：不必一步到位把所有规范都挂上去。优先把团队最在意、又最容易被忽略的环节（如提交信息、主干分支的代码风格）设成硬卡点，其余逐步补充；
• 区分硬卡与提示：对主干、发布分支可以让插件在检查不通过时强制卡住（默认行为，具体以各插件为准）；对特性分支或初期推行阶段，也可以先设成只提示、不阻断，等团队适应后再收紧；
• 结合分支保护：CNB 支持对指定分支设置保护规则，要求合并前必须通过 CI 检查。把规范检查挂到受保护分支的流水线里，就能形成"规范检查 + 代码评审 + CI 卡点"的完整门禁；
• 规范与插件同步更新：团队规范调整后，记得同步更新对应的插件配置或规则，让机器执行的标准和团队约定保持一致。

这样，规范就不再是文档里落灰的文字，而是流水线里持续运转的关卡，每一次提交、每一个 PR 都会被自动过一遍。

七、规范靠机器执行，比靠记忆更稳

代码规范写在文档里没人看，根源不在团队不认真，而在于"靠文档 + 靠自觉"的执行方式天生容易打折扣。把它跑进流水线、用插件自动卡点，规范就从"供人翻阅"变成"供机器执行"，执行力度和稳定性都明显提升。

CNB 的插件市场提供了 commitlint、go-lint、cpplint、markdown-lint、phplint 等静态检查插件，以及 git-pr-title-lint、git-pr-limit 这类 PR 维度的检查工具，覆盖了从提交信息到代码风格、再到 PR 规模的多个层面。把它们挂进 .cnb.yml 流水线，团队就能拥有一套自动运转的规范门禁。

如果你的代码规范也还躺在文档里没人看，不妨把它搬进流水线，用插件让规范自动卡起来。

想了解怎么配，可前往 腾讯云 CNB 参照官方流水线配置，在仓库 .cnb.yml 里挂上 commitlint 和对应语言的 lint 插件，把代码规范从文档搬进流水线，让每一次提交都自动过一遍规范检查。