Flutter 生态包发布指南自动 CI 发布、批量发布与坏版本恢复全流程【免费下载链接】flutterFlutter makes it easy and fast to build beautiful apps for mobile and beyond项目地址: https://gitcode.com/GitHub_Trending/flutter41/flutter本文基于 Flutter 仓库中面向生态团队的发布文档 release/README.md在 生态文档索引 中列为 Releasing a Plugin or Package编写系统讲解 flutter/packages 仓库中插件与包的完整发布链路自动发布 CI 的触发与判定规则、面向高频变更包的批量发布Batch release配置与流程、手动发布的标准操作与检查清单以及已发布坏版本的修复与撤回策略。读完本文你将能够理解一个包的版本变更如何最终到达 pub.dev并掌握作为生态维护者应对发布失败、坏版本事故的完整处置方案。总则任何版本变更都应被发布Flutter 生态的发布基线是一条简单原则任何修改了包版本的 PR这应该是绝大多数 PR都应发布到 pub.dev。这条规则贯穿后文所有发布模式——无论是自动发布、批量发布还是手动发布目标都是保证pubspec.yaml中的版本号与 pub.dev 上可安装的版本严格一致让包的使用者包括大量不经常更新传递依赖的客户端能稳定解析到预期版本。发布方式的选择取决于包的流量特征自动发布Automatic release默认模式master 上每个包含版本更新的提交都会触发发布批量发布Batch release面向高流量包把多个提交聚合成一次周期性发布避免CHANGELOG.md和pubspec.yaml频繁冲突、pub.dev 上版本号不断滚动。自动发布Automatic releaseflutter/packages 仓库中的包通过一个名为release的 GitHub Action 工作流自动发布。其工作机制是当master 分支的某个提交包含一个或多个包的版本更新时releaseCI 会把新版本发布到 pub.dev并向 GitHub 推送发布标签tag该 CI 在以下任一情况下视为通过发布流程成功该提交不包含任何版本更新无事可做新版本此前已经发布过幂等。运行时机与阻塞行为有几个 CI 行为细节值得注意releaseCI只在 post-submit 阶段运行并且会等待其他所有 CI 任务全部通过后才开始——这保证了只有整体质量验证通过的提交才会被发布与其他 CI 任务一样releaseCI 一旦失败会阻塞后续的 PR因此发布失败必须及时处理见下文release CI 失败怎么办注意例外releaseCI不会自动发布flutter_plugin_tools包它本身就是发布工具链的一部分单独管理。新包的首次发布与所有权转移当一个包首次发布时它会归属于发布器账户publisher account而不是 flutter.dev 认证发布者verified publisher。需要拥有发布器账户权限的团队成员登录 pub.dev通过包页面的Admin 标签页把包转移给认证发布者。这一步是所有新包接入生态发布体系的必经环节。release CI 失败了怎么办原文档给出了清晰的故障处置路径抖动flake场景例如网络问题团队成员可以直接重跑该 CI复杂场景团队成员可以先手动发布相关包流程见后文手动发布再重跑 CI 使其通过最常见的失败原因其实是其他测试任务先失败了而不是发布本身出错。如果那次测试失败是抖动导致的正确顺序是先重跑失败的测试任务待其变绿后再重跑release。批量发布Batch release对于 PR 数量多的包默认每个提交发一次版会带来两个问题CHANGELOG.md与pubspec.yaml的合并冲突不断pub.dev 上版本持续滚动。这类包可以启用批量发布把多个提交聚合成一次周期性发布。硬性前提启用批量发布的包必须处于正式版本号不能是预发布版本如x.y.z-dev因为批量发布工具链不支持预发布版本。启用步骤启用批量发布需要提交一个 PR包含以下四处改动1. 在包根目录添加ci_config.yamlrelease: batch: true这个文件也是判定包发布模式的依据——包根目录存在ci_config.yaml且设置了release: batch: true即视为批量发布否则默认走自动发布。2. 在包根目录创建pending_changelogs目录并放入template.yaml模板文件# Use this file as a template to draft an unreleased changelog file. # Make a copy of this file in the same directory, give it an appropriate name, and fill in the details. changelog: | - Can include a list of changes. - with markdown supported. version: major|minor|patch|skip贡献者后续为每个 PR 复制该模板、重命名并填写变更说明version字段声明该变更期望的版本级别major / minor / patchskip表示本次不升版本。3. 在工作流目录添加名为package_name_batch.yml的工作流文件package_name为包名name: Creates Batch Release for package_name on: workflow_dispatch: schedule: # Run every Monday at 8:00 AM. Update cron as needed. - cron: 0 8 * * 1 jobs: dispatch_release_pr: runs-on: ubuntu-latest permissions: contents: write steps: - name: Repository Dispatch uses: peter-evans/repository-dispatch5fc4efd1a4797ddb68ffd0714a238564e4cc0e6f with: event-type: batch-release-pr client-payload: {package: package_name}该工作流支持手动触发workflow_dispatch和定时触发示例 cron 为每周一 8:00通过 repository dispatch 事件batch-release-pr通知后续流程。4. 为两个既有工作流添加分支触发条件——release_from_branches.yml与sync_release_pr.yml的on.push.branches中都要加上on: push: branches: - release-package_name-*合并该 PR 后批量发布即配置完成。批量发布的日常工作流启用后贡献者不应再直接修改CHANGELOG.md或pubspec.yaml而是为每个 PR 在pending_changelogs目录新增一个变更文件。之后的发布过程自动进行package_name_batch.yml中的定时任务触发一个指向release-package_name-version分支的新发布 PR该 PR 把pending_changelogs中的所有文件聚合成对CHANGELOG.md和pubspec.yaml的一次更新版本号按各条目声明的级别推进包属主package owner评审并合并该 PR合并动作触发release_from_branches.yml把包发布到 pub.dev同时sync_release_pr.yml创建一个指向main分支的同步 PR把发布分支上的变更同步回主干包属主评审并合并同步 PR周期结束。这一设计的关键在于变更在周期内以独立文件形式存在几乎不可能产生冲突版本号与 CHANGELOG 的写入被收敛到一次性的聚合 PR 中实现了高流量、低摩擦的发布节奏。手动发布Manual release手动发布是兜底手段只在自动发布被阻断时使用。典型触发场景是带外破坏out-of-band breakage导致 post-submit 测试因与被发布 PR 无关的原因失败从而卡住了本应自动发布的版本。文档同时指出对于影响面较广涉及很多插件的 PRrevert 后重新落地是手动发布之外的一个值得优先考虑的替代方案。发布前的三个检查文档要求发布前逐条确认post-submit CI 是否为绿如果因带外破坏而未全绿也要确认后续存在一个未改动任何与该插件相关内容的绿色 post-submit。发布前必须检查 post-submit CI 状态发布即永久Publishing is foreverpub.dev 上的版本不可覆盖。虽然 bug 或破坏性变更理应已在 PR 评审中被捕获但这是上线前最后一次的 revert 机会不要在周五发布发布前考虑是否有较长的不可用时段即将到来。新版本可能存在 bug 或引发使用者提问如果此时无法跟进问题的发现与解决周期会被显著拉长。标准操作步骤使用仓库工具链flutter_plugin_tools完成发布git checkout commit_hash_to_publish——这应当就是你要发布的那个 PR 的提交除非有非常充分的理由使用其他版本确认git status干净且本地仓库没有多余文件例如通过git clean -xfd清理运行flutter_plugin_tools的publish命令。该命令会检查上一步的清理状态把新版本发布到 pub.dev并按package_name-vpackage_version格式为提交打标签再把标签推送到上游仓库。完全手动备选方案如果第 3 步中无法使用flutter_plugin_tools可以退化为纯手动三步用dart pub publish把包更新推送到 pub.dev用git tag按package_name-vpackage_version格式为提交打标签用git push upstream tagname把标签推送到上游 master 分支。恢复坏版本Recovering from a bad release尽管有重重防护破坏性问题仍可能在包发布之后才被发现。这里有一个与 flutter/engine、flutter/flutter 仓库根本不同的约束已发布过破坏性变更的 PR 不能直接 revert——revert 会把包带回一个更早的版本号而那个版本同样已经发布过pub.dev 不允许重复发布同一版本号。正确的修复路径是以一个新版本落地修复视具体情况选择revert 并带上版本号和 CHANGELOG 更新或正向修复fix-forward可选撤回坏版本。如果坏版本发布在最近七天内flutter.dev发布者组成员可以通过包 pub.dev 页面的 Admin 标签页撤回retract该版本。撤回这一步在两种情况下尤其有价值坏版本的问题与错误的 Flutter/Dart 版本约束有关例如包依赖了新版 Flutter/Dart 的功能却没有设置对应的最低版本约束即使后续发布了修正约束的新版本仍在使用旧版 Flutter 的客户端可能继续解析到坏版本撤回可以杜绝这种解析结果作为修复版本推广期间的即时止损防止在修复版本铺开前更多用户被波及。文档特别强调撤回应当与发布修复版本同时进行而不是替代它——这样已经被破坏的用户才能顺畅地到达一个可用状态。相关联的生态发布流程理解发布链路后以下同仓库文档可作为延伸阅读它们与发布过程直接衔接Updating-Packages-repo-for-a-stable-release.md描述每个 stable Flutter 版本发布后如何更新 flutter/packages 仓库的 stable 版本钉扎、Flutter-Dart 版本映射、N-1/N-2 遗留分析测试与最低 Flutter 版本约束——这是版本发布在 SDK 维度的配套动作与包维度的 pub.dev 发布互为表里。文档给出了具体命令示例例如用仓库工具批量抬升最低 SDK 版本dart run script/tool/bin/flutter_plugin_tools.dart update-min-sdk --flutter-min3.44.0以及用update-release-info --versionnext只更新受影响包的发布说明contributing/README.md定义进入发布流水线的上游规则——版本与 CHANGELOG 更新规范、## NEXT段的使用、批量发布包pending_changelogs变更文件的写入要求以及破坏性变更的分批落地策略先临时加publish_to: none隔离不可发布状态再集中落地破坏性变更最后统一升版Package-migration-to-1.0.0.md解释包跨越 1.0.0 里程碑时的生态摩擦——由于 pub 对 0.x 版本采用语义偏移从0.x.y到1.0.0属于主版本跃迁文档建议依赖方在过渡期使用0.x.yz 2.0.0的宽约束而非^1.0.0以减少生态碎片化。这直接影响发布时约束字段的写法决策。从本仓库结构看Flutter 还有另一条独立的发布通道dev/bots/prepare_package.dart 负责把 Flutter git 仓库打包成 SDK 分发包要求完整 40 位--revision、--branch等参数dev/bots/unpublish_package.dart 则负责从云存储移除已发布的 SDK 归档并回滚各 channel 的元数据——两者面向的是 Flutter SDK 本身的 dev/beta/stable 通道分发与本文讨论的包发布pub.dev是两套机制阅读时应注意区分。小结Flutter 生态的包发布体系可以概括为三层默认层是 master 提交触发的自动发布 CI保证改版本即发布且发布前置所有 CI 验证效率层是批量发布用ci_config.yaml、pending_changelogs与三个协作工作流把高频变更收敛为周期性聚合发布兜底层是手动发布与坏版本恢复前者以post-submit 全绿、发布即永久、避免周五发布为检查清单后者以新版本修复 七天内撤回双管齐下。三者共同保障了 pub.dev 上版本、仓库 tag 与 CHANGELOG 三者的一致性。【免费下载链接】flutterFlutter makes it easy and fast to build beautiful apps for mobile and beyond项目地址: https://gitcode.com/GitHub_Trending/flutter41/flutter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考