Lit 如何执行一次 monorepo 版本发布：Version Packages PR 与 GitHub Actions 审批流程

Lit 如何执行一次 monorepo 版本发布：Version Packages PR 与 GitHub Actions 审批流程

【免费下载链接】litLit is a simple library for building fast, lightweight web components.项目地址: https://gitcode.com/GitHub_Trending/li/lit

这篇文章面向 Lit 核心贡献者，描述一次完整的 monorepo 版本发布操作：在main分支上有未发布的 changeset 时，如何通过两次 GitHub Actions 审批完成发版——第一次审批触发 "Version Packages" PR 的创建，第二次审批真正把新版本发布到 npm 和 GitHub Release。整套流程的文档依据是 dev-docs/lit-release-process.md，配套的工作流定义在 .github/workflows/release.yaml。

发版前有一个前提：确认main分支已经被导入并在 Google 内部测试通过（Lit 在 Google 中是未分版本号的 monorepo，这样可以保证不会意外发布破坏性变更）。这一点需要在团队的 Discord general development channel 中确认。

流程总览

整个发布可以概括为四步：

1. 在待发布的 commit 上审批 "Release / Release" GitHub Action；
2. 代码审查自动创建的 "Version Packages" PR；
3. Squash and merge 该 PR；
4. 在 "Version Packages" PR 产生的 commit 上再次审批 "Release / Release" workflow，发布到 npm 和 GitHub。

理解 release.yaml 的结构有助于明白为什么要审批两次：该 workflow 在 push 到main时触发，且只在github.repository == 'lit/lit'时运行（fork 仓库不会执行）。任务绑定在受保护的Changesets环境（environment: Changesets）下，这正是每次运行都需要人工点击审批的原因。核心步骤由changesets/action@v1.5.1执行，配置为version: npm run version、publish: npm run release，对应根 package.json 中的两个脚本：

• version：npm run changeset version && npm run update-version-vars
• release：npm run build && npm run changeset publish

CI 中使用 Node 24.5，npm ci安装依赖。changesets 的具体行为由 .changeset/config.json 决定：baseBranch为main，changelog 使用仓库自定义的./changelog-lit.cjs生成器，updateInternalDependencies为minor。

第一次审批：触发 Version Packages PR

1. 在仓库的 commits 页面找到要发布的main分支 commit，点击代表 GitHub Action checks 的黄色圆点（或红色叉号）。此时应该有一个处于 pending 状态的 Action 叫 "Release / Release (push)"，点击 "Details" 进入详情。
2. 点击 "Review pending deployments" 链接，进入 Release workflow 的 GitHub Actions 页面，点击 "Review deployments" 并批准这次 pending 部署。

审批后，changesets action 会自动生成一个标题为 "Version Packages" 的 PR。

如果审批后 "Version Packages" PR 没有出现，说明 GitHub Action 运行中发生了错误，需要查看完整日志定位原因。文档中记录过的一种失败是：格式错误的 changeset 文件引用了不存在的包名。修复方式是把修正后的 changeset 文件提交到main，然后在新 commit 上重新走发布流程。

审查 Version Packages PR 时要核对什么

向熟悉待发布包的团队成员请求代码审查。这个 PR 的变更目的有四个：

1. 删除所有 changeset 文件，把内容并入各包的 CHANGELOG 文件；
2. 全局提升版本号；
3. 提升各package.json中的版本号；
4. 如需要，提升相关package.json中的依赖范围（只在 minor 或 major 发布时预期出现）。

审查时要重点找的错误：

• 新包版本错设为 1.0.0：新建并发布的包容易把package.json版本设成 1.0.0，导致 Changeset 把版本提升到 2.0.0。正确做法是新建包时版本设为 0.0.0；
• major 版本发布：major 发布或 minor 新特性需要更仔细审查，major 发布是重大事件，需要团队协调；
• 伞形包同步：lit-html、lit-element、@lit/reactive-element等核心库的 changelog 更新应反映在伞形lit包中；
• 内部包不应发版：私有或尚不 ready 的包不应该获得 changelog 或版本提升。

发现错误时的处理路径是：关闭自动生成的 "Version Packages" PR，把修正提交到main分支，然后重新运行发布流程。

Squash and merge：一个容易踩的坑

"Version Packages" PR 获得批准后（前提是期间没有新的 changeset 合入main），执行 squash and merge。

这里有一个硬约束：如果 PR 处于打开状态期间main上又产生了新 commit 并带入了新的 changeset 文件，不要squash and merge。正确做法是重新运行 version packages 来刷新 PR。否则后续的发布步骤不会真正 publish，而是会再生成一个整合了新 changeset 文件的 "Version Packages" PR。

文档给出的判断依据是：只有当main上没有未发布的 changeset 文件时，才会真正发生 publish。

第二次审批：发布到 npm 与 GitHub Release

合并 "Version Packages" PR 后，找到它产生的 commit，等待至少tests-local检查通过，然后重复第一次审批的操作：点击该 commit 上的 "Release / Release" Action，进入 "Review pending deployments" 并批准部署。

这次批准的结果就是发布：changesets action 执行publish: npm run release（即npm run build && npm run changeset publish），把新版本发布到 npm，并创建 GitHub release。同时 workflow 还会检查本次发布是否包含lit包本身（通过 scripts/extract-published-lit-version.js 提取），如果是，会把lit-all.min.js和lit-core.min.js等 bundle 推送到 lit 的 dist 仓库并打上v${LIT_VERSION}tag。

验证发布结果

完成发布后做两项确认：

1. 到仓库的 releases 页面检查新的 release notes 是否生成；
2. 到 npm 上对应包的页面确认新版本已经发布。

两项都确认，这次发布就算完成。

发布后操作（可选分支）

以下操作不属于发版主路径，只在需要时执行。

自动生成发布图片：创建 "Version Packages" PR 时，"Generate Release Image" action 会自动生成一张发布图片。到仓库的release-image.yamlworkflow 页面找到最上面那条 workflow，其中的 releaseimage zip artifact 就是发布图片文件。

手动生成发布图片：当需要生成多张图片或渲染自定义 markdown 时使用 packages/internal-scripts 中的release-image工具。以下命令从litmonorepo 根目录执行，每个命令生成一个release.png；不带参数运行该命令可查看用法。

为同一包的多个版本生成图片（文档示例）：

cd packages/internal-scripts && npm run build && npx release-image \ -f ../lit-html/CHANGELOG.md -v 2.0.1 \ -f ../lit-html/CHANGELOG.md -v 2.0.0

从一个 markdown 文件生成图片：

cd packages/internal-scripts && npm run build && npx release-image -m release.md

注意-m（markdown 文件）与-f（changelog 文件）不能同时使用；-f指定的路径必须与对应包的package.json同目录，工具会从中读取包名。

更新 lit.dev 生成的 API 文档：如果本次发布包含新的 API 文档，lit.dev 站点需要更新——复制本次发布 commit 的 sha，替换 lit.dev 仓库中 API 文档配置里的旧 sha，执行npm run build重建，构建成功后pages.json和/或symbols.json会包含新文档；若这两个文件未变化，说明 API 文档没有变更。然后把变更提交到 lit.dev 仓库（该操作发生在另一个仓库，不在本 monorepo 内）。

对外沟通：在 Twitter 和 Discord 上公告新版本。

边界与限制

• 该流程只适用于 Lit 核心贡献者，依赖对仓库的 GitHub Actions 环境审批权限；fork 仓库上的 push 不会触发 Release workflow。
• 发布只覆盖main分支上未发布的全部变更（changeset 驱动的整仓发版），不存在"只发布某个包"的分支路径；内部包是否发版靠审查阶段把关（不应获得 changelog 或版本提升）。
• 发布后main上必须没有未发布的 changeset 文件，否则下一次合并 "Version Packages" 不会 publish，只会继续生成新的 "Version Packages" PR。
• bundle 的 dist 仓库推送只发生在本轮发布包含lit包本身时，只发 labs 或其他包不会更新 dist 仓库。

【免费下载链接】litLit is a simple library for building fast, lightweight web components.项目地址: https://gitcode.com/GitHub_Trending/li/lit