开源发布工程

引言

发布是开源项目里最容易被低估的工程环节。写代码有评审、有 CI、有测试覆盖，而「发一个版本」在很多项目里就是维护者手动打个 tag、填一下 release notes、上传几个文件。直到某天发现：某个平台的二进制漏传了、变更日志里漏了一条破坏性变更、某个下游因为 minor 版本里的行为变化而炸掉、或者三年前的一个版本出了漏洞却没人知道该往哪个分支打补丁。

工程上的难点有三层。第一层是版本号是契约：你写 1.4.0，下游就会按 ^1.4.0 去约束，这个承诺一旦破坏，信任成本极高。第二层是发布是多人协作的产物：制品来自不同平台、不同构建机、不同维护者，任何一个人漏了步骤，产物就不一致。第三层是发布是长期责任：发出去就要准备打补丁，LTS 分支、回移、EOL 公告都是发布工程的一部分，而不是「发完就完」。

还有一条常被忽略：发布频率与质量并不线性相关。发得太频繁，下游升级疲劳，破坏性变更被淹没在噪声里；发得太少，修复迟迟到不了用户手里，用户只能自己打补丁或换项目。找到合适的节奏并把它制度化，是发布工程的核心目标之一。

本文按「版本契约 → SemVer 边界 → 变更日志 → 流水线 → 多平台制品 → 签名与完整性 → 节奏与 LTS → 弃用与迁移 → 发布清单」展开。需要划清两条边界：发布节奏作为健康度指标怎么解读见开源项目健康度度量 ，本文讲的是维护者这一侧的工程实践；安全补丁的协调披露流程见开源漏洞响应与 CVE 流程 ，本文只讲「补丁怎么发布出去」。读者对象是维护者与负责发布流水线的工程师。

目录

1. 版本号是契约
2. 语义化版本的边界与常见误用
3. 变更日志规范
4. 发布流水线设计
5. 多平台构建与制品矩阵
6. 制品签名与发布物完整性
7. 发布节奏与 LTS 策略
8. 弃用与破坏性变更的迁移路径
9. 发布清单与回滚方案

1. 版本号是契约

版本号不是「第几次发布」的计数，而是对下游的兼容性承诺。三个数字各有明确含义，破坏含义就等于破坏契约。

MAJOR.MINOR.PATCH 的语义（SemVer 2.0.0）：
  MAJOR  有不兼容的变更（破坏性）
  MINOR  向后兼容地新增功能（可含标记为 deprecated 的内容）
  PATCH  向后兼容地修 bug（不新增功能、不改行为契约）

预发布与构建元数据：
  1.4.0-alpha.1 / 1.4.0-rc.2   预发布，优先级低于 1.4.0
  1.4.0+build.20261007         构建元数据，不参与优先级比较

契约的具体形态是下游写的约束表达式。^1.4.0 表示「允许 1.x 里大于等于 1.4.0 的版本」，~1.4.0 表示「允许 1.4.x」，=1.4.0 表示「只要这一个」。你发 1.5.0 时，所有写 ^1.4.0 的下游都会自动升级——如果这个版本里有行为变化，就是一次静默破坏。

因此判断「算不算破坏性变更」的标准不是「我改了多少代码」，而是**「下游在什么情况下会因此出错」**。改一个导出的函数签名、把默认值从 A 改成 B、删除一个已弃用接口、把某个依赖升到不兼容的 major、甚至改变一个 JSON 字段的输出顺序（如果下游依赖了顺序），都是破坏性变更。

最后一条最考验判断力：「修 bug 导致行为变化」到底算 PATCH 还是 MAJOR。经验法则是看「下游有没有可能依赖了这个 bug」。如果这个 bug 的行为被文档化过、或大量下游为绕过它写了 workaround，那么修它就是破坏性的，应当走 MAJOR 并写清迁移方式。宁可保守地判成 MAJOR，也不要让下游在一次 npm update 后莫名崩溃。

2. 语义化版本的边界与常见误用

SemVer 只覆盖「有稳定公开 API 的库」。对应用（而非库）、对 0.x 阶段的项目、对以数据格式或协议为接口的项目，它的规则需要调整，滥用会带来反效果。

0.x 的含义被严重误用。 SemVer 规定 0.y.z 阶段「任何东西都可能随时变」。现实中大量项目长期停在 0.x，把 0.9 到 0.10 当 minor 发破坏性变更，下游却因为某些包管理器的约束规则（如 ^0.9.0 只允许 0.9.x）而困在旧版本。正确做法是：要么尽快发 1.0.0 明确稳定承诺，要么在 README 里显式声明「0.x 期间 minor 可能破坏兼容」，不要指望下游去读 SemVer 细则。

0.x 阶段的两种务实策略：
  A. 快速进入 1.0：一旦 API 被外部使用，就发 1.0 并承诺兼容
  B. 显式声明不稳定：README 写明 0.x 的 minor 可含破坏性变更
     （此时下游应使用 =0.9.3 精确约束）

应用不该照搬 SemVer。 一个部署服务、一个 CLI 工具、一个终端产品，它们的「用户」不是代码而是人，用户不会写 ^1.4.0，也不在意 PATCH 与 MINOR 的区别。这类项目用 YYYY.MM 日历版本（如 2026.10）或纯递增版本反而更清晰。强行用 SemVer 会出现「为了符合 SemVer 而把破坏性变更藏进 major 里攒着一起发」的怪象。

「接口」不一定只是函数。 配置文件的字段名、环境变量、CLI 参数、HTTP 响应结构、数据库 schema、插件 API、甚至错误码，都是下游可能依赖的契约。把这些纳入兼容性判断范围，是成熟项目的标志。建议维护一份「公开接口清单」，明确哪些是承诺稳定的、哪些是「内部实现，随时可变」。

插件生态有一个额外要求：插件 API 要单独版本化。核心项目发 2.0 时，如果插件 API 没有独立版本号，所有插件作者都得跟着猜「我的插件还能不能用」。做法是给插件 API 一个独立的兼容性版本（如 pluginApiVersion = 3），核心在加载插件时校验，不匹配则给出明确错误。

3. 变更日志规范

变更日志是版本契约的人可读版本。它最重要的价值不是「记录改了什么」，而是让下游判断「这次升级对我有没有影响」。因此它的结构必须围绕「影响」组织，而不是围绕「提交」。

Keep a Changelog 的六类条目（按对下游的影响排序）：
  Removed    移除的功能/接口，破坏性最强
  Changed    现有行为的变更，可能破坏下游
  Deprecated 即将移除，提前预警
  Added      新增功能，通常安全
  Fixed      修复，通常安全（除非下游依赖了旧行为）
  Security   安全相关修复，需要优先升级

不要用 commit 列表当变更日志。 git log 的输出对下游毫无意义：fix typo、refactor parser、bump deps 这类提交与「我需要做什么」无关。变更日志要写面向使用者的影响：不是「重构了配置解析」，而是「配置文件中的 timeout 字段现在按秒解释，此前按毫秒，旧值需除以 1000」。

写变更日志的工程化做法有两条。第一条是在 PR 里写变更条目：每个 PR 在合并时必须添加一个 changelog 片段文件（如 .changelog/1234.md），发布时自动拼接。这样条目与代码同步产生，不会等到发布时凭记忆补。

  # 用 changelog 片段目录 + 发布时聚合（towncrier 风格）
  .changes/
    1234.feature.md    "支持 YAML 配置文件"
    1240.removed.md    "移除已弃用的 --legacy-flag"
    1251.security.md   "修复配置文件路径穿越"

第二条是从提交类型自动生成：如果团队严格遵循 Conventional Commits（feat: / fix: / feat!:），可以用工具（如 git-cliff、release-please）自动分类生成。代价是要求所有提交规范化，好处是零维护成本。两种方式都行，关键是必须有人负责「面向使用者的措辞」——自动生成常把内部术语直接抛给用户。

还有一条硬性建议：变更日志里给每个破坏性变更附迁移指南。一段「把 foo(a, b) 改成 foo({a, b})，示例见迁移文档」比十行「优化了 API 设计」有用得多。迁移成本决定了下游会不会升级，而升级率决定你的修复能不能到达用户。

4. 发布流水线设计

发布流水线的目标是让「发版」从一串手工步骤变成一次可复现的触发。核心原则是：同一个 tag 触发同一条流水线，产出同一组制品，任何人都能复现，且失败可重跑。

  # .github/workflows/release.yml 骨架
name: release
on:
  push:
    tags: ['v*.*.*']
permissions:
  contents: write
  id-token: write          # 无密钥签名需要
jobs:
  build:
    strategy:
      matrix:
        include:
          - {goos: linux,   goarch: amd64}
          - {goos: linux,   goarch: arm64}
          - {goos: darwin,  goarch: arm64}
          - {goos: windows, goarch: amd64}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: {fetch-depth: 0}
      - run: make build GOOS=${{matrix.goos}} GOARCH=${{matrix.goarch}}
      - run: cosign sign-blob --yes dist/* --output-signature ...
  publish:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: ./scripts/create-release.sh   # 聚合制品、生成校验和、发布

流水线里几个不能省的细节：

• fetch-depth: 0：默认浅克隆拿不到完整历史，导致 git describe、版本推导、变更日志生成全部出错。
• 构建产物与源码分离：构建 job 只产出制品并上传 artifact，发布 job 只负责聚合与上传。这样重跑发布不需要重新构建。
• 生成校验和文件：每个制品附 SHA-256，聚合到一个 SHA256SUMS 里并签名，下游才能校验。
• 失败要能重跑：发布流程中任何一步失败，都能从该步重跑而不重头来。这要求每一步幂等。

# 生成校验和并签名（发布流水线最后一步）
sha256sum dist/*.tar.gz dist/*.zip > dist/SHA256SUMS
cosign sign-blob --yes dist/SHA256SUMS --output-signature dist/SHA256SUMS.sig

流水线的触发方式建议只用 tag 触发，不用分支。分支触发的「发布」容易在合并时误触发，而 tag 是显式的、不可重复的发布意图。tag 命名统一为 vX.Y.Z（带 v 前缀），与包管理器的版本号剥离前缀后一致，避免两套版本号。

5. 多平台构建与制品矩阵

开源项目的用户环境极其分散，制品矩阵通常包括：操作系统（Linux/macOS/Windows）、架构（amd64/arm64/riscv64）、打包格式（tar.gz/zip/deb/rpm/容器镜像）、语言生态（npm/PyPI/Maven/Go module）。矩阵越大，越需要自动化，手工维护必然出错。

典型制品矩阵（按交付渠道分类）：
  二进制包    tar.gz / zip，按 OS×ARCH 组合
  系统包      deb / rpm / apk，按发行版
  容器镜像    多架构 manifest（linux/amd64 + linux/arm64）
  语言包      npm / PyPI / Maven Central / NuGet
  源码包      源码 tarball + 校验和（发行版打包者需要）

交叉编译 vs 原生构建要按语言权衡。Go、Rust、C 支持交叉编译，一台机器能产出所有平台的二进制，成本最低，但 CGO 或依赖系统库时会变复杂。需要原生环境的语言（如某些 JNI、C 扩展）只能用「每平台一台构建机」的矩阵。无论哪种方式，都要保证同一 tag 的所有制品来自同一次构建，避免「Linux 版是昨天的 commit，Windows 版是今天的」。

# Go 交叉编译示例：一次产出多平台
for os in linux darwin windows; do
  for arch in amd64 arm64; do
    GOOS=$os GOARCH=$arch CGO_ENABLED=0 \
      go build -trimpath -ldflags "-s -w -X main.version=$VERSION" \
      -o "dist/app_${VERSION}_${os}_${arch}" ./cmd/app
  done
done

-trimpath 去掉构建路径（避免泄漏本地目录结构、也提升可复现性），-ldflags "-s -w" 去符号表减小体积，-X main.version=$VERSION 把版本号编进二进制——让 app --version 能正确回答，比让用户猜自己装的是哪版重要得多。

容器镜像用 buildx 产多架构 manifest：

docker buildx build --platform linux/amd64,linux/arm64 \
  --tag registry.example.com/app:1.4.0 --push .

多架构镜像的关键是打一个 manifest list，让 docker pull 按宿主架构自动选层。只推单架构镜像、然后在文档里写「arm64 用户请用 :1.4.0-arm64」，是常见但很差的体验。相关容器实践可参考 Docker 与容器基础 。

GoReleaser 是这一类工作的成熟方案，一份配置能覆盖二进制、容器镜像、系统包、语言包、校验和、签名与 release notes，且与 CI 集成良好。自研脚本不是不行，但要意识到你在重造一个已经解决得很好的轮子。

6. 制品签名与发布物完整性

发布物的完整性要解决两个问题：「我下载的这个文件有没有被篡改」和「它是不是官方发布的」。前者靠校验和，后者靠签名，两者缺一不可。

# 校验和：解决传输损坏与简单篡改
sha256sum -c SHA256SUMS

# 签名：解决来源伪造
cosign verify-blob --signature SHA256SUMS.sig --certificate SHA256SUMS.pem \
  --certificate-identity-regexp 'https://github.com/org/app/.github/workflows/release.yml@refs/tags/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  SHA256SUMS

校验和单独存在时价值有限：攻击者替换了制品，也可以顺手替换 SHA256SUMS。只有把校验和签名，才形成「官方身份 → 校验和 → 全部制品」的信任链。签名机制本身（Sigstore 无密钥签名、透明日志）在软件供应链与 SBOM里有完整讨论，这里只强调发布环节的三条要求：

1. 签校验和文件，而不是逐个签每个制品：一个签名覆盖全部制品，下游校验一次即可。
2. 在发布文档里给出可复制的验证命令：把 cosign verify-blob ... 和身份参数直接写进 README 与 release notes，下游才会真的去验。
3. 提供 GPG 备选：仍有相当多的发行版打包者和老用户依赖 GPG 签名，同时发布 SHA256SUMS.asc 覆盖这部分需求。

发布物的最小完整集合：
  制品本体        app_1.4.0_linux_amd64.tar.gz 等
  校验和          SHA256SUMS
  签名            SHA256SUMS.sig（Sigstore）+ SHA256SUMS.asc（GPG 备选）
  变更日志        CHANGELOG 的对应段落
  源码包          app-1.4.0.tar.gz（供发行版打包）

还有一条容易忽略：不要只发布到 GitHub Releases。很多用户通过包管理器（Homebrew、apt、scoop）获取，如果这些渠道的版本落后或缺失，用户就会被困在旧版本。发布清单里应当包含「各分发渠道是否都已更新」这一项，并在 CI 里做一次自动核对（如抓取 Homebrew formula 的版本号与最新 tag 比对）。

7. 发布节奏与 LTS 策略

发布节奏是维护者精力的可见刻度。节奏稳定本身就是一种承诺：下游知道「每两个月有一个 minor」，就能规划升级窗口。节奏紊乱（半年不发、然后连发三个）会让下游无所适从。

三种典型节奏：
  列车制（Train）    固定周期发版（如每 6 周），内容随到随发，不等待
  特性制（Feature）  攒够一批功能才发，节奏不固定
  按需制（On-demand） 有重要修复就发，minor 不频繁

选择依据：
  下游是「产品团队」→ 列车制，可预期
  下游是「库作者」→ 列车制 + 稳定的 minor 语义
  下游是「终端用户」→ 按需制 + 日历版本

列车制是大型项目的主流（Kubernetes 每约 15 周一个 minor，Node.js 每约 6 个月一个 major）。它的核心纪律是「不等待」：没赶上的特性顺延到下个版本，不为了塞功能而延期。这让发布日期成为硬承诺，下游可以据此排期。

LTS 策略是发布节奏的长期延伸，对基础设施类项目尤其重要。一份合格的 LTS 政策要回答四个问题：哪些版本进入长期支持（通常是最新的 1~2 个 major）、支持窗口多长（建议 ≥ 12 个月）、安全补丁是否回移到旧分支、EOL 是否有提前公告期（建议 ≥ 6 个月）。

LTS 政策模板要点：
  支持范围    1.28、1.29（当前 + 上一个 major）
  支持窗口    每个 major 自发布起 14 个月
  补丁范围    仅安全修复与严重 bug，不回移新特性
  公告期      EOL 前 6 个月在官网与 release notes 公告
  分支策略    release-1.28 / release-1.29 长期存在，按需打补丁

没有政策本身就是最差的政策。如果项目不打算维护旧版本，就在 README 明确写「只维护最新 major，升级是最快的安全路径」，让下游据此做架构决策。含糊其辞会让下游以为有保障，出事时才发现没有。

8. 弃用与破坏性变更的迁移路径

破坏性变更无法避免，能控制的是下游迁移的成本。成熟的发布工程把「弃用」当作一个跨越多个版本的过程，而不是一次性的删除。

破坏性变更的三阶段：
  阶段一 弃用（当前 major）
    - 在文档中标记 deprecated，给出替代方案
    - 运行时打印弃用警告（含迁移指引与计划移除的版本）
    - 保留旧接口，行为不变
  阶段二 缓冲（下一个 minor 或补丁）
    - 提供自动迁移工具（codemod）或兼容层
    - 迁移指南随文档发布，含前后对照示例
  阶段三 移除（下一个 major）
    - 在 major 版本中删除，变更日志中列在 Removed 首位
    - 迁移指南链接进 release notes

弃用警告要可操作。「foo is deprecated」是无用的警告，正确的写法是「foo(a, b) 已弃用，将在 2.0 移除，请改用 foo({a, b})，参见迁移指南 §3」。警告里带上替代写法，能让下游在运行时直接看到怎么改。

提供 codemod 是降低迁移成本最有效的手段。用 jscodeshift、comby、或自研脚本，把常见的调用模式自动改写，下游跑一条命令就能完成大部分迁移：

npx @org/codemod-1-to-2 src/   # 自动改写 1.x 到 2.x 的常见用法

不是所有项目都值得投入写 codemod，判断标准是下游数量 × 破坏面。下游上千、破坏的是高频 API，codemod 的投入几天就能收回；下游几十个、破坏的是冷门接口，写一份清晰的迁移指南就够了。

给下游留出时间。一个破坏性变更从弃用到移除，至少应跨一个 minor 周期（建议 3~6 个月）。急于在一个版本里「弃用即移除」，会直接摧毁下游的信任——他们下次面对你的 major 升级时会选择不升。

9. 发布清单与回滚方案

把发布流程固化成一份清单，能消除绝大多数「漏了一步」的事故。清单要在 CI 里能自动核对的部分就自动化，人工只做判断类的事。

发布前 checklist：
  [ ] 主干 CI 全绿（含集成测试与端到端测试）
  [ ] CHANGELOG 已更新，破坏性变更列在 Removed/Changed 首位
  [ ] 版本号在源码、包元数据、文档中一致（自动核对）
  [ ] 破坏性变更的迁移指南已发布
  [ ] 依赖的许可证与安全扫描通过
  [ ] 预发布版本（rc）已在测试环境验证

发布中 checklist：
  [ ] tag 从正确 commit 打出（vX.Y.Z，签名 tag）
  [ ] 全平台制品构建成功且命名一致
  [ ] SHA256SUMS 生成并签名
  [ ] 各分发渠道（Releases/镜像仓库/包管理器）均已更新

发布后 checklist：
  [ ] 在干净环境里安装并跑通快速上手流程
  [ ] 校验和与签名可验证（模拟下游验证一次）
  [ ] 公告发布（release notes、邮件列表、社交渠道）
  [ ] 记录本次发布耗时与问题，作为下次改进输入

发布后必须在干净环境验证。发布者本地往往残留着旧版本、缓存、环境变量，直接测会假绿。用容器或干净虚拟机安装刚发布的制品，走一遍文档里的快速上手流程——这一步能抓住「制品漏文件」「文档与制品不符」「依赖没打进去」等大量问题。

回滚方案常被忽略。发布出去的东西无法「撤回」（用户已经下载了），但可以做三件事：把有问题的版本在包管理器上标记为 yank/deprecate、发布一个修复版本并置顶、在各渠道公告明确「请勿使用 X.Y.Z，改用 X.Y.(Z+1)」。因此发布清单里应当包含**「万一这个版本有问题，第一步做什么」**的预案。

# 撤回一个 npm 版本（不是删除，而是标记为弃用并指向修复版）
npm deprecate "app@1.4.0" "存在严重缺陷，请升级到 1.4.1"
# PyPI 只能 yank，不能删除
# GitHub Release 可以标记为 pre-release 并编辑说明

永远不要删除已发布的版本。删除会让下游的构建直接失败（锁定文件里的版本找不到了），影响面远大于留着一个坏版本。正确做法是保留制品、标记弃用、发布修复版。

权衡取舍

核心取舍是维护者精力与下游体验的平衡。发布工程里的每一项（LTS、codemod、多平台制品、签名）都要消耗维护者有限的时间，而维护者精力本身就是稀缺资源。原则是：自动化的部分尽量做全（制品、校验和、签名、渠道同步都能自动化），需要人判断的部分明确划线（支持多久、破坏性变更何时移除，写进政策就不必每次纠结）。

常见坑清单

• minor 里塞破坏性变更：下游的 ^ 约束会静默升级到出错——判断标准是「下游会不会因此出错」而非「改了多少」。
• 修 bug 改了行为却不发 major：下游可能依赖了旧行为——先问「这个 bug 被依赖过吗」。
• 变更日志直接贴 commit 列表：对下游无意义——必须写面向使用者的影响与迁移方式。
• 浅克隆导致版本推导失败：fetch-depth: 0 不能省，否则 git describe 与变更日志全错。
• 制品漏平台或命名不一致：用户装不上或脚本匹配失败——矩阵化构建 + 发布后核对。
• 只发校验和不签名：攻击者可同时替换制品与校验和——必须签校验和。
• 用浮动 tag 引用基础镜像或 action：内容会悄悄变化——钉 digest / commit SHA。
• 破坏性变更「弃用即移除」：下游来不及迁移，信任受损——至少跨一个 minor 周期。
• 发布后不在干净环境验证：本地缓存造成假绿——用容器或干净虚拟机走一遍快速上手。
• 删除已发布的版本：下游锁定文件失效，构建直接崩——只标记弃用，不删除。
• 各分发渠道版本不一致：部分用户被困在旧版——发布清单里核对各渠道。
• 没有 LTS 政策却不说明：下游误以为有保障——要么给政策，要么明确「只维护最新版」。

小结

开源发布工程的本质是把「发一个版本」变成一条可复现、可验证、可长期维护的流水线。它由三部分构成：契约（版本号与变更日志定义你对下游承诺了什么）、机制（流水线、多平台制品、签名保证交付物正确且可信）、责任（LTS、弃用策略、迁移路径保证承诺在长期内成立）。三者缺一，发布就会退化成「手动打 tag」的偶然事件。

落地顺序建议从变更日志与版本策略开始：先明确「什么算破坏性变更」，再让每个 PR 带变更片段，然后固化发布流水线，最后补签名与 LTS 政策。跳过前两步直接上流水线，通常以「自动化地发布了一堆没人看得懂的变化」告终。

如果想继续深入，建议沿两条线读：一条是度量侧，从开源项目健康度度量看发布节奏如何作为项目健康信号被解读，理解下游是怎么评估你的发布行为的；另一条是安全侧，从开源漏洞响应与 CVE 流程看安全补丁如何走一条比常规发布更快的特殊通道，把「常规发布」与「应急发布」两套流程都准备好。