企业官网建设流程全解析

• 无人机
• 嵌入式
• 智能硬件

本文以 INAV 开源项目发布管理实践为基础，系统讲解从「合并固件 PR」到「正式发布固件与 Configurator」的完整版本发布流程。文中覆盖双仓库版本号管理、RC 版本字符串规范、基于夜间构建（nightly）的先验证后打标签原则、SITL 与 WASM 二进制更新、macOS 代码签名时序、PG 参数组结构校验、变更日志生成与 GitHub Release 管理，读者按此手册即可安全、可重复地完成一次 INAV 版本发布。

一、一次 INAV 发布包含什么

INAV 的发布不是一个单仓库动作，而是固件 + 桌面配置工具（Configurator）两个仓库的协同发布：

• 固件仓库（inav）：编译出各飞控目标板的.hex固件，以及各平台的 SITL（软件在环）模拟器二进制；
• Configurator 仓库（inav-configurator）：桌面配置软件，需要内嵌与固件版本配套的 SITL 二进制（10.x 起还包含浏览器端 WASM SITL 与 PWA 构建产物）。

两个仓库必须以匹配的版本号分别打标签。10.x 之后的发布还增加了第三条产物链：feature/wasm-sitl-firmware分支构建的 WASM SITL 会打包进 PWA（浏览器版 Configurator）中，与原生平台 SITL 并列作为发布资产。

该文档在设计上就面向可执行命令的编码助手（如 Claude Code），发布过程中可以用脚本自动化一部分步骤；每次发布后也应把经验教训回写到本文档中。

二、版本号管理

2.1 语义化版本

INAV 使用标准语义化版本MAJOR.MINOR.PATCH：

版本号在两个仓库中各自维护：

• 固件：定义在仓库根目录 CMakeLists.txt 的project(INAV VERSION X.Y.Z)指令中。例如当前仓库中该行即为project(INAV VERSION 10.0.0)（第 56 行）。
  • 查看：grep -E 'project\(INAV VERSION' CMakeLists.txt
  • 更新：直接编辑CMakeLists.txt中的版本号
• Configurator：定义在package.json的"version"字段。
  • 查看：jq -r .version package.json或node -p "require('./package.json').version"
  • 更新：npm version <X.Y.Z> --no-git-tag-version

从源码看，固件版本号会被进一步贯穿到运行期：project(INAV VERSION ...)产生的FIRMWARE_VERSION编译进固件，src/main/build/version.h 中的FC_VERSION_MAJOR/MINOR/PATCH_LEVEL组合出FC_VERSION_STRING，最终由 src/main/fc/fc_msp.c 的MSP_FC_VERSION处理函数（第 488-492 行）通过 MSP 协议上报给 Configurator——这也解释了为什么两个仓库的版本号必须严格一致。

2.2 RC 版本字符串规范（先定规格再动手）

在开始任何发布工作之前，必须先确定规范的版本字符串。RC 版本必须使用小写rc并用连字符-与版本号连接：

这条规则并非洁癖：Configurator 的固件刷写器（Firmware Flasher）使用区分大小写的正则表达式解析固件文件名。大写RC或下划线分隔符会导致目标板名称被误读，即使发布上传成功，固件在刷写器列表中也不可见。

三、两条铁律：先验证再打标签 & PR CI 只在创建时运行

3.1 铁律一：永远不要给未经完整测试的提交打标签

错误的顺序会带来不可逆的后果：如果先打标签再发现构建损坏，你会留下一个指向坏提交的标签。因此操作顺序被强制规定为：

1. 将全部固件 PR 合并到发布分支；
2. 确保发布分支在nightly-build.yml的触发列表中（不在则通过 PR 添加）；
3. 推送到发布分支以触发夜间构建（合并 workflow PR，或推送一个琐碎提交）；
4. 等待夜间构建完成，确认所有任务（jobs）都通过；
5. 从inav-nightly下载固件产物（内含 Configurator 所需的 SITL 二进制）；
6. 在 Configurator 仓库更新 SITL 二进制（10.x 还含 WASM SITL 与 PWA 支持），等 CI 通过后合并——这触发 Configurator 的夜间构建；
7. 通过夜间构建干跑（dry-run）Configurator 签名（不推标签）：用codesign --verify与xcrun stapler validate验证其 macOS 产物已签名并公证；
8. 仅当第 7 步的干跑通过后，才推送 Configurator 版本标签（触发release.yml，产出签名 + 公证的 macOS 构建）；
9. 下载签名后的 Configurator 产物并逐一核验（代码签名、SITL、PWA/WASM）；
10. 在 Linux 与 Windows 上手动测试；
11. 最后才创建引用已验证提交/标签的 GitHub Releases。

为什么固件是「先验证后标签」，而 Configurator 有例外？因为 Configurator 的签名 macOS 构建由标签推送触发，所以它的「先验证」环节就是第 7 步的夜间干跑——先确认夜间构建的 macOS 产物已签名，再推标签。CI 失败或任何验证失败都必须先修复问题，绝不能给坏提交打标签。

3.2 铁律二：GitHub Actions CI 在 PR 创建时运行，而不是合并时

这一平台特性直接决定了发布流程的形态：

• 每个 PR 的 CI 产物只包含该 PR 分支的变更；
• 合并多个 PR 后，没有任何一次 CI 运行包含全部已合并变更；
• 因此夜间构建工作流必须包含发布分支，才能得到包含全部变更的完整产物。

nightly-build.yml在推送到指定分支时触发，并把完整产物（hex 文件 + SITL）上传到inav-nightly仓库。检查触发分支列表，示例：

on: push: branches: - master - maintenance-8.x.x - maintenance-9.x # 新增维护分支时在此追加！

如果维护分支不在列表中，需要创建一个 PR 把它加进去。

3.3 获取完整固件产物

全部 PR 合并到发布分支之后：

1. 确认发布分支已在nightly-build.yml触发列表中（没有就先加）；
2. 向发布分支推送任意提交以触发夜间构建（必要时可以是空白/注释等琐碎改动）；
3. 等待夜间构建完成；
4. 从inav-nightly的 Releases 下载产物：

gh release list --repo iNavFlight/inav-nightly --limit 5 gh release download <tag> --repo iNavFlight/inav-nightly

只有夜间构建的产物才包含全部已合并的变更。

四、发布前检查清单

4.1 代码就绪

• 计划内的 PR 全部合并
• 目标分支 CI 通过
• 无阻塞发布的关键未解决问题
• 两个仓库的版本号均已更新
• Configurator 中的 SITL 二进制已更新
• WASM SITL 已构建并放入 Configurator 的js/web/WASM/（10.x+）
• PG 结构校验通过（详见下文「PG 参数组校验」）

4.2 文档

• 发布说明草稿已就绪
• 破坏性变更已记录
• 新功能已记录
• 大版本升级时创建 Configurator 迁移配置（migration profile）——具体步骤见 Backup Restore Architecture

五、八步发布工作流

1. 验证固件发布就绪 ├── 固件仓库全部 PR 已合并 ├── 版本号已更新 ├── 固件目标提交的 CI 通过 └── PG 结构校验通过 2. 先下载固件产物 ├── 从 CI 下载固件 hex 文件 ├── 从同一次 CI 运行下载 SITL 二进制 ├── 如需（glibc ≤2.35 兼容性）本地构建 Linux x64 SITL ├── 构建 WASM SITL 固件（10.x+） └── 为 Configurator 备好 SITL 二进制 + WASM SITL 3. 更新 Configurator 中的 SITL（及 WASM SITL） ├── 用第 2 步的 SITL 二进制创建 PR（10.x 还需 WASM 产物 + SITL-Webassembly.js 导入修正） ├── 等待 Configurator CI 通过 └── 合并 SITL 更新 PR 4. 构建 PWA、干跑签名，然后推标签并下载 Configurator 产物 ├── WASM SITL 就位后构建 PWA（yarn web:build，10.x+） ├── 通过夜间构建干跑签名（不推标签）：对夜间 macOS 产物执行 codesign --verify + stapler validate ├── 干跑通过后推送版本标签（v*.*.*）触发 release.yml（签名 + 公证 macOS） ├── 从该次 release.yml 运行下载 ├── 验证 macOS DMG 已签名且无跨平台文件混入 ├── 验证 Windows SITL（cygwin1.dll 存在） ├── 验证 Linux SITL（glibc ≤ 2.35 兼容 Ubuntu 22.04） └── 自动化 SITL 验证（glibc 检查、二进制可运行） 5. 手动测试 ├── 在 Linux 上测试 Configurator + SITL ├── 在 Windows 上测试 Configurator + SITL ├── 在 macOS 上测试 Configurator + SITL（如有条件） └── 确认各平台基本功能正常 （此时 Configurator 标签已推送——正是它产出了签名构建； 固件标签仍是「先验证后打标签」） 6. 生成变更日志 ├── 列出上次标签以来的 PR ├── 分类变更 └── 格式化发布说明 7. 创建草稿 Release（仅在手测通过之后） ├── 为固件创建标签 + 草稿 Release（指向已验证提交）——先验证后打标签 ├── 创建 Configurator Release，引用已推送的标签 ├── 上传已验证产物（10.x+ 含 PWA 输出） └── 附加发布说明 8. 审查与发布 ├── 最终审查草稿 Release ├── 维护者批准 └── 发布 Releases

六、更新 SITL 二进制

6.1 存放位置

SITL 二进制必须发布前更新到 Configurator 仓库，目录结构为：

inav-configurator/resources/public/sitl/ ├── linux/ │ ├── inav_SITL │ └── arm64/inav_SITL ├── macos/ │ └── inav_SITL └── windows/ ├── inav_SITL.exe └── cygwin1.dll

6.2 从夜间构建下载

# 找到匹配的夜间版本 gh release list --repo iNavFlight/inav-nightly --limit 5 # 下载 SITL 资源 curl -L -o /tmp/sitl-resources.zip \ "https://github.com/iNavFlight/inav-nightly/releases/download/<tag>/sitl-resources.zip" unzip /tmp/sitl-resources.zip -d /tmp/sitl-extract # 复制到 Configurator cd inav-configurator cp /tmp/sitl-extract/resources/sitl/linux/inav_SITL resources/public/sitl/linux/ cp /tmp/sitl-extract/resources/sitl/linux/arm64/inav_SITL resources/public/sitl/linux/arm64/ cp /tmp/sitl-extract/resources/sitl/macos/inav_SITL resources/public/sitl/macos/ cp /tmp/sitl-extract/resources/sitl/windows/inav_SITL.exe resources/public/sitl/windows/ # 提交 git add resources/public/sitl/ git commit -m "Update SITL binaries for <version>"

6.3 本地构建 Linux x64 SITL（推荐）

CI 构建的 Linux x64 SITL 二进制可能要求比 Ubuntu 22.04 LTS 更高的 glibc 版本。为确保兼容所有受支持的 Ubuntu LTS，建议在 Ubuntu 22.04（glibc 2.35）上本地构建 Linux x64 SITL：

cd inav mkdir -p build_sitl cd build_sitl cmake -DSITL=ON .. make -j$(nproc)

二进制输出在build_sitl/bin/SITL.elf。验证 glibc 依赖：

objdump -T build_sitl/bin/SITL.elf | grep GLIBC | sed 's/.*GLIBC_//;s/ .*//' | sort -V | tail -1 # 应输出 2.35 或更低

何时本地构建、何时用 CI 产物：

• 本地构建：Linux x64（确保 glibc ≤ 2.35）
• 直接用 CI 产物：Windows（含 cygwin1.dll）、macOS、Linux arm64

本仓库中 Building SITL 也给出了 SITL 的构建前提：需要真正的 GCC（gcc13 或更新，macOS 除外）、Unix socket 网络（Windows 上需 Cygwin）与 pthreads，Linux 上同样使用cmake -DSITL=ON .. && make。

七、验证打包构建中的 SITL

7.1 Windows SITL 验证

Windows SITL 必须依赖cygwin1.dll才能运行，缺失时用户会得到 "cygwin1.dll not found" 错误。

# 检查 Windows zip 是否同时包含两个必需文件 # 注意：打包构建使用 resources/sitl/（而非 resources/public/sitl/） unzip -l INAV-Configurator_win_x64_9.0.0.zip | grep -E "(cygwin1.dll|inav_SITL.exe)" # 期望输出（两个文件都必须存在）： # 2953269 12-19-2024 01:41 resources/sitl/windows/cygwin1.dll # 1517041 12-21-2024 17:25 resources/sitl/windows/inav_SITL.exe

如果cygwin1.dll缺失：不要发布——Windows SITL 将会是坏的。

7.2 Linux SITL glibc 验证

Linux SITL 二进制必须用足够老的 glibc 编译，以支持所有未 EOL 的 Ubuntu LTS：

# 检查 glibc 版本需求（应输出 2.35 或更低） objdump -T inav_SITL | grep GLIBC | sed 's/.*GLIBC_//;s/ .*//' | sort -V | tail -1

如果 glibc > 2.35，二进制在 Ubuntu 22.04 上会报错：

/lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found

7.3 路径差异速查

打包构建中forge.config.js的extraResource配置会把resources/public/sitl复制为resources/sitl。

八、macOS 代码签名与 PWA（10.x+）

8.1 签名时序三条规则

发布就绪的 macOS 构建由.github/workflows/release.yml代码签名并公证（notarized），该工作流在标签推送（v*.*.*或*.*.*）时触发。PR 的 CI 从不签名；夜间构建在完整密钥集存在时会签名并公证。三条硬规则：

1. 推标签前先通过夜间构建验证签名。已推送的标签实质不可变，不要盲打标签。SITL PR 合并后夜间构建会自动运行——用codesign --verify和xcrun stapler validate检查其 macOS 产物，两项都通过才推标签（任一项失败，说明六个签名密钥缺失，release.yml也必然失败）。
2. SITL 就位后才推标签。原生 SITL 二进制（10.x 还含 WASM SITL）必须先提交并合并进 Configurator 仓库，否则签名的.app/.dmg会携带过期 SITL。
3. 签名后绝不改动 macOS 产物。不再重新打包、重新捆绑或重新签名。需要修复就提交代码并推新标签。

这套约束在代码层面也有对应实现：SITL 清理在afterCopyExtraResources钩子中运行（签名之前）；签名后从 bundle 删除文件会导致公证失败（详见 Configurator 仓库CLAUDE.md的 "macOS Code Signing & Notarization" 章节）。

如果夜间构建没有触发：优先给release.yml增加workflow_dispatch:，然后用gh workflow run release.yml --ref <commit>运行（同样的失败即关闭的测试、不打标签）。最后的手段是推一个临时测试标签（如10.0.0-sign-test，符合*.*.*），验证后再删除，然后推送真正的10.0.0-RC1标签。

8.2 WASM SITL 与 PWA 构建

10.x 起的浏览器端 PWA Configurator，在原生平台 SITL 二进制之外，还会捆绑一个浏览器内运行的 WASM 版 SITL：

1. 从feature/wasm-sitl-firmware分支构建 WASM SITL 固件：cmake .. -DTOOLCHAIN=wasm; make SITL；
2. 将输出重命名为inav_<ver>_WASM.js/.wasm，复制到inav-configurator/js/web/WASM/，并更新js/web/SITL-Webassembly.js中硬编码的导入路径；
3. 构建 PWA：yarn web:build→ 输出到dist-web/；
4. 把 PWA 输出作为 Configurator 的额外资产上传（打包格式与维护者确认）。

WASM SITL 与原生 SITL 都必须在发布 CI 运行之前就位。

九、打标签与发布

标签只应在产物测试通过、确认可以发布后创建——Configurator 除外：它的签名 macOS 构建由推标签（触发release.yml）产生，所以在推标签之前要先通过夜间构建干跑签名并确认 macOS 产物已签名 + 公证。固件始终是「先验证后打标签」。

9.1 查看最新标签

# 固件 cd inav git fetch --tags git tag --sort=-v:refname | head -10 # Configurator cd inav-configurator git fetch --tags git tag --sort=-v:refname | head -10

9.2 创建并推送标签

固件先验证再打标签；Configurator 先夜间干跑签名再推标签（推标签触发签名构建），然后创建 Release。

# 固件（先验证产物） cd inav git pull git tag -a <version> -m "INAV <version>" git push origin <version> # Configurator —— 先用夜间构建干跑签名（codesign --verify + stapler validate）， # 再推标签（此推送触发 release.yml → 签名 + 公证 macOS） cd inav-configurator git pull git tag -a <version> -m "INAV Configurator <version>" # 或 v<version> git push origin <version>

十、变更日志生成

10.1 列出上次标签以来的 PR

cd inav LAST_TAG=$(git describe --tags --abbrev=0) gh pr list --state merged --search "merged:>=$(git log -1 --format=%ai $LAST_TAG | cut -d' ' -f1)" --limit 100

10.2 核验每个 PR 是否在正确分支上

把 PR 写进发布说明之前，必须确认它确实合并进了发布分支，而不是未来分支。gh pr list按合并日期列出 PR，与目标分支无关——合并到maintenance-10.x的 PR 也会出现，即使它不在当前版本中。

# 确认某 PR 的合并提交存在于发布分支 git log upstream/maintenance-9.x --oneline | grep <short-sha> # 或查看该分支最近的合并提交 git log upstream/maintenance-9.x --oneline --merges | head -30

如果 PR 不在输出中，就从发布说明里排除。

10.3 使用 git log

LAST_TAG=$(git describe --tags --abbrev=0) git log $LAST_TAG..HEAD --oneline --merges

10.4 变更日志格式

## INAV <version> Release Notes ### Firmware Changes #### New Features - PR #1234: Description (@contributor) #### Bug Fixes - PR #1236: Description (@contributor) #### Improvements - PR #1237: Description (@contributor) ### Configurator Changes #### New Features - PR #100: Description (@contributor) ### Full Changelog **Firmware:** <前版本标签>...<新版本标签> 对比 **Configurator:** <前版本标签>...<新版本标签> 对比

十一、PG（参数组）校验：发布前防 EEPROM 损坏的守门员

创建标签之前必须运行 PG 校验，防止 EEPROM 损坏类缺陷流入发布版本：

cd inav ./cmake/validate-pg-for-release.sh

✅ 通过：继续发布。❌ 失败：创建 hotfix PR，在受影响结构的PG_REGISTER宏中递增 PG 版本号，然后重新运行。

11.1 脚本做了什么（源码级解读）

从本仓库的 cmake/validate-pg-for-release.sh 可以看到完整实现逻辑：

1. 构建参考目标：脚本以SPEEDYBEEF745AIO为参考目标执行make SPEEDYBEEF745AIO.elf（构建失败退出码 2），然后对生成的 ELF 用arm-none-eabi-nm --print-size提取所有pgResetTemplate_符号，从而得到每个参数组的当前结构体大小；
2. 读取注册信息：在src/main的.c文件中定位对应的PG_REGISTER行，解析出结构体类型与第 4 个参数（PG 版本号）；
3. 与参考数据库比对：将当前大小/版本与 cmake/pg_struct_sizes.reference.db 中记录的条目比对：
   • 新结构体自动追加进数据库；
   • 大小变化但版本号未递增 →校验失败（退出码 1）；
   • 大小变化且版本已递增 → 视为合法变更，自动更新数据库。

11.2 为什么版本号必须递增

看 src/main/config/parameter_group.h 的PG_REGISTER宏族可知，每个参数组通过PG_REGISTER(_type, _name, _pgn, _version)注册，注册项中.pgn = _pgn | (_version << 12)——PG 版本号被编码在参数组号的高位。固件升级时若结构体布局（大小/偏移）改变而版本号未递增，老版本 EEPROM 数据按新结构解析就会错位，直接导致配置损坏。这正是发布前必须跑./cmake/validate-pg-for-release.sh的根本原因。

十二、下载发布产物

12.1 固件 hex 文件

固件由夜间构建系统产出：

# 列出最近夜间构建 gh release list --repo iNavFlight/inav-nightly --limit 5 # 下载 hex 文件 gh release download <nightly-tag> --repo iNavFlight/inav-nightly --pattern "*.hex"

12.2 本地构建固件（如需要）

⚠️ 发布用构建务必使用 Release 模式以节省磁盘空间：

cd inav mkdir build-release cd build-release cmake -DCMAKE_BUILD_TYPE=Release .. # 构建全部官方发布目标 make release # 或构建特定目标 make MATEKF405 MATEKF722

磁盘占用：Release 模式约 4–6 GB，而默认 RelWithDebInfo 模式约 109 GB（缩减约 96%）。最终.hex中本来就会剥离调试符号，因此 Release 模式产出与默认模式完全相同。

make release目标在 CMake 层有明确语义：本仓库 cmake/main.cmake 的collect_targets()会收集所有未被SKIP_RELEASES属性标记的目标（各目标的CMakeLists.txt中通过target_stm32f405xg(XXX SKIP_RELEASES)等方式标记），聚合为一个release自定义目标。也就是说make release构建的就是官方发布目标清单。

12.3 重命名固件文件

去除 CI 后缀，RC 版本追加 RC 编号：

RC_NUM="rc2" # 正式版留空 # 先检查是否存在 .hex 文件，避免 glob 报错 if compgen -G "*.hex" > /dev/null; then for f in *.hex; do target=$(echo "$f" | sed -E 's/inav_[0-9]+\.[0-9]+\.[0-9]+_(.*)_ci-.*/\1/') version=$(echo "$f" | sed -E 's/inav_([0-9]+\.[0-9]+\.[0-9]+)_.*/\1/') if [ -n "$RC_NUM" ]; then mv "$f" "inav_${version}-${RC_NUM}_${target}.hex" else mv "$f" "inav_${version}_${target}.hex" fi done else echo "No .hex files found to rename." fi

12.4 Configurator 构建

从 GitHub Actions CI 下载：

# 列出最近的工作流运行 gh run list --repo iNavFlight/inav-configurator --limit 10 # 下载产物（每个平台产物一个子目录） gh run download <run-id> --repo iNavFlight/inav-configurator # 关键：按平台归类——绝不把所有文件扁平化到一个目录。 # 扁平化可能把 Windows .exe 塞进 macOS DMG（曾造成 9.0.0 发布事故）。 mkdir -p linux/ macos/ windows/ mv INAV-Configurator_linux_*/* linux/ mv INAV-Configurator_macOS*/* macos/ mv INAV-Configurator_win_*/* windows/ rmdir INAV-Configurator_*

十三、创建 GitHub Releases

13.1 创建草稿 Release

RC 版本要加--prerelease，让 GitHub 标记为预发布、不显示为最新稳定版。用--target <commit-sha>指向特定提交（比指向当前 HEAD 更安全，且本地仓库被锁定时也能用）：

# 固件（RC 发布） gh release create 9.1.0-rc1 \ --repo iNavFlight/inav \ --target <commit-sha> \ --title "INAV 9.1.0-rc1 release candidate for testing" \ --notes-file release-notes.md \ --prerelease \ --draft gh release upload 9.1.0-rc1 firmware-dir/*.hex --repo iNavFlight/inav # Configurator（RC 发布） gh release create 9.1.0-rc1 \ --repo iNavFlight/inav-configurator \ --target <commit-sha> \ --title "INAV Configurator 9.1.0-rc1 release candidate for testing" \ --notes-file release-notes.md \ --prerelease \ --draft gh release upload 9.1.0-rc1 linux/* macos/* windows/* --repo iNavFlight/inav-configurator # 正式版：相同命令，去掉 --prerelease

13.2 管理 Release 资产

通过 API 重命名资产：

# 获取 Release 与资产 ID gh api repos/iNavFlight/inav/releases --jq '.[] | select(.draft == true) | {id: .id, name: .name}' gh api repos/iNavFlight/inav/releases/RELEASE_ID/assets --paginate --jq '.[] | "\(.id) \(.name)"' # 重命名某个资产 gh api -X PATCH "repos/iNavFlight/inav/releases/assets/ASSET_ID" -f name="new-filename.hex"

删除草稿 Release 中的过期资产（如上次上传尝试的残留），再上传新文件：

gh api -X DELETE "repos/iNavFlight/inav/releases/assets/ASSET_ID"

13.3 发布顺序

先发布固件，确认 Configurator 能识别它之后，再发布 Configurator：

# 第 1 步：发布固件 gh release edit <version> --repo iNavFlight/inav --draft=false

第 2 步：人工确认固件出现在 Configurator 固件刷写器中

打开 INAV Configurator → Firmware Flasher 页签 → 勾选 "Show unstable releases"。新固件版本必须出现在发布列表中——这确认了 GitHub Release 格式正确、文件名正则解析无误。

同时选一个名称含空格的目标（如MAMBAH743 2022B GYRO2），确认它以空格而非下划线显示——这验证了多词目标名解析正确。

如果固件没有出现：检查文件名是否严格符合inav_<version>-rc<n>_<TARGET>.hex（小写rc、连字符分隔），参见下文「资源命名规范」。

# 第 3 步：仅在固件于刷写器验证通过后发布 Configurator gh release edit <version> --repo iNavFlight/inav-configurator --draft=false

十四、资源命名规范

固件（RC）：inav_<version>-rc<n>_<TARGET>.hex固件（正式）：inav_<version>_<TARGET>.hex

Configurator（RC）：INAV-Configurator_<platform>_<version>-rc<n>.<ext>Configurator（正式）：INAV-Configurator_<platform>_<version>.<ext>

十五、维护分支

发布新大版本时，创建维护分支：

• maintenance-X.x：用于版本 X 的缺陷修复；
• maintenance-(X+1).x：用于面向下一大版本的破坏性变更。

完整的分支模型与目标分支选择规则见 Development.md 的 "Branching and release workflow" 章节。该章节明确了：INAV 使用基于版本的分支（如maintenance-9.x、maintenance-10.x）进行活跃开发与发布；向后兼容的变更应从当前大版本分支分叉并合入它，破坏性变更则走下一大版本分支；不要从master分支或合入master——master不参与开发与发布流程，只是维护者定期合并当前维护分支的兜底。

15.1 创建维护分支

COMMIT_SHA="<完整40位SHA>" # inav gh api repos/iNavFlight/inav/git/refs -f ref="refs/heads/maintenance-9.x" -f sha="$COMMIT_SHA" # inav-configurator gh api repos/iNavFlight/inav-configurator/git/refs -f ref="refs/heads/maintenance-9.x" -f sha="$COMMIT_SHA"

15.2 将发布分支的变更前推到下一版本

当某个补丁版本的变更也需要落在下一大版本分支上时，完整流程见 merging-release-into-next-version.md。要点：从目标（较新）分支分出审查分支（如merge/9.1-into-10.x），在其上把旧分支合并进来并解决冲突，再以 PR 形式合入较新维护分支；合并提交只落在较新分支上，旧发布分支完全不被触碰。不要使用 GitHub 的 "Resolve conflicts" 按钮——它会反向把整个较新分支并进旧分支，污染旧发布分支。

十六、Hotfix 发布

发布后发现关键缺陷时：

1. 从发布标签创建 hotfix 分支；
2. Cherry-pick 或编写修复；
3. 标签为X.Y.Z+1（patch 递增）；
4. 按常规流程构建并发布；
5. 在发布说明中记录为 hotfix。

十七、发布后任务

• 公告发布（Discord、论坛等）
• 更新任何被钉住的 issue
• 监控关键缺陷报告
• 准备必要的 hotfix
• 把经验教训回写进本文档

结语

一次成功的 INAV 发布，本质上是把「验证」全部前移：用夜间构建验证包含全部合并变更的完整产物，用夜间干跑验证 macOS 签名链路，用 PG 校验防止 EEPROM 兼容性事故，用手动测试兜底，最后才打标签、建草稿 Release 并先固件后 Configurator 地发布。遵循本文的顺序与检查点，可以避免打标签后发现构建损坏、SITL 文件缺失、跨平台产物污染等经典发布事故。对本仓库内的源码依据（版本定义、release目标、PG 校验脚本与注册宏），可分别查阅 CMakeLists.txt、cmake/main.cmake、cmake/validate-pg-for-release.sh 与 src/main/config/parameter_group.h 继续深入。

• 无人机
• 嵌入式
• 智能硬件