企业官网建设流程全解析

• 硬件开发
• 嵌入式
• 科研

LibreVNA 是一个 100 kHz 至 6 GHz 的 2 端口 USB 矢量网络分析仪（VNA）开源项目。除了正式发布版外，仓库的 GitHub Actions 会为master分支上的每一个 commit 自动编译出全套 PC 端 GUI 与嵌入式固件二进制文件，供希望尝鲜最新功能的用户直接下载使用。本文以仓库文档 DownloadActionBuilds.md 为主线，讲清"从哪个 commit、哪次 workflow run、下载哪个 artifact"的完整定位方法，并结合仓库中的 workflow 定义与打包脚本，说明每个二进制文件的来源、命名规则与内容构成。

背景：为什么需要从 Actions 下载构建产物

官方文档明确说明：仓库的 GitHub Actions 被设置为针对master分支的每次 commit 生成二进制文件（原文："binary files are created for each commit on the master branch"），欢迎用户试用这些每日构建以体验最新特性，但也要做好遇到未完成功能（unfinished things）的准备。

这与 README 中 Quick Start 一节的说法一致：想体验最新特性时，每个 commit 的编译版本可以在 Actions 页面找到（"compiled versions of each commit can be found here"），并且明确提示部分功能可能不稳定或不完整（"some features might be unstable or incomplete"），同时把本文对应的下载指引 DownloadActionBuilds.md 作为下载遇到障碍时的参考文档（见 README.md）。

从仓库结构看，这套自动构建由 .github/workflows 目录下的多个 workflow 文件驱动，其中与"下载二进制"直接相关的是：

• Build.yml：产出全部可下载二进制的构建 workflow；
• Test.yml（workflow 名为Unit_Tests）：每次 commit 同步触发的单元测试 workflow，不产出任何 artifact。

原文档提醒读者"每个 commit 会触发两次 workflow run，一次用于二进制、一次用于自动化测试"，二者的区分正是本文后续下载步骤中最容易出错的地方。

构建 workflow 如何工作：从源码看产物来源

理解产物的命名与内容，最可靠的方式是直接阅读 Build.yml。该 workflow 在master分支的push和pull_request事件上触发，包含 6 个并行 job，每个 job 负责一个平台或产物：

其中<version>由 workflow 在构建时动态生成。以 Ubuntu job 为例（见 Build.yml）：

# 1) 生成构建时间戳 run: echo "timestamp=$(date +%Y-%m-%d-%H-%M-%S)" >> $GITHUB_OUTPUT # 2) 从工程文件中提取版本号（GUI 版本） cd Software/PC_Application/LibreVNA-GUI fw_major=`grep -oP '(?<=FW_MAJOR=)[0-9]+' LibreVNA-GUI.pro` fw_minor=`grep -oP '(?<=FW_MINOR=)[0-9]+' LibreVNA-GUI.pro` fw_patch=`grep -oP '(?<=FW_PATCH=)[0-9]+' LibreVNA-GUI.pro` echo "app_version=v$fw_major.$fw_minor.$fw_patch-${{steps.id_date.outputs.timestamp}}" >> $GITHUB_OUTPUT

也就是说，版本号 = 源码中的 FW_MAJOR/FW_MINOR/FW_PATCH 三位版本号 + 构建时间戳。在当前仓库快照中，LibreVNA-GUI.pro 定义为FW_MAJOR=1 FW_MINOR=6 FW_PATCH=5，嵌入式侧 VNA_embedded/Makefile 中为-DFW_MAJOR=1 -DFW_MINOR=6 -DFW_PATCH=5且硬件修订号为-DHW_REVISION="'B'"；文档中的历史截图（2024 年 3 月）则显示为v1.5.1系列，可见每日构建的版本号会随 master 分支的提交而演进。

各 artifact 的实际内容

• GUI 类 artifact：构建命令为qmake LibreVNA-GUI.pro && make -j9。Windows job 额外执行windeployqt并复制libwinpthread-1.dll、libgcc_s_seh-1.dll、Qt6OpenGL.dll等运行时依赖，因此上传的是自包含的release目录（见 Build.yml）；macOS 两个 job 会执行macdeployqt后将LibreVNA-GUI.app压缩为 zip 上传（Build.yml）；Ubuntu 与 RPi5 job 上传的是未压缩的单一可执行文件。
• 嵌入式固件 artifact：Embedded_Firmwarejob 用gcc-arm-none-eabi工具链执行make（VNA_embedded/Makefile），随后调用根目录的打包脚本 AssembleFirmware.py 生成组合固件，最终 artifact 内含两个文件：VNA_embedded.elf与combined.vnafw（见 Build.yml）。

combined.vnafw是微控制器通过 USB 直接刷入设备的完整固件包。从 AssembleFirmware.py 的实现可以看出其结构：

FPGA_BITSTREAM = "FPGA/VNA/top.bin" # FPGA 位流 HEADER_SIZE = 24 # 固定 24 字节头部 f.write(bytes("VNA!", 'utf-8')) # 文件起始的 4 字节魔数

• 头部依次写入 FPGA 位流与 MCU 固件的起始地址和大小（共 4 个 4 字节小端整数），再写入两者串联计算的 CRC32（初值0xFFFFFFFF，先算位流再算 MCU 固件，见 AssembleFirmware.py）；
• MCU 固件会在Debug/、Release/、build/三个候选路径中取修改时间最新的一个VNA_embedded.bin；
• 整个文件结尾会填充零字节到 256 的整数倍（AssembleFirmware.py），便于设备端按扇区处理。

脚本还内置了自检：若写入字节数不等于HEADER_SIZE（24）则报错退出，保证头部布局与设备端解析逻辑严格一致。

第一步：切换到 Actions 标签页

打开仓库页面后，在顶部导航栏中点击Actions标签（与Code、Issues、Pull requests等并列）。原文档第 1 步即指向此处（截图 Binaries1.png）。

进入后默认显示All workflows列表，展示仓库所有 workflow 的运行记录。

第二步：选对 commit 与 workflow run（关键步骤）

原文档指出：每个 commit 会触发两次 workflow run——一次产出二进制（Build），一次运行自动化测试（Unit_Tests）。请选择 build 编号更高的那一次。

上图中每条记录左侧会标注Build #740、Build #741这类全仓库递增的构建编号。由于两次 run 几乎同时触发，它们的编号相邻，原文档给出的经验法则是选择编号更高的那次。选定后进入 run 详情，需要核对界面是否为下面这种"正确"的样子。

第三步：确认选中的是 Build run 而非 Test run

正确的 run 详情应显示Build.yml，状态Success，并带有若干 artifact 与多个 job：

如果你看到的界面是下面这样——只有一个Testsjob、Artifacts 显示为———说明你误选了测试 workflow run（它不包含任何二进制）：

从 Test.yml 的定义可以印证这一现象：它只是编译Software/PC_Application/LibreVNA-Test单元测试工程并以./LibreVNA-Test -platform offscreen运行（Test.yml），全程没有任何upload-artifact步骤，因此永远不会有可下载的产物。

第四步：滚动到 Artifacts 区域下载

在正确的 Build run 页面底部向下滚动，即可看到Artifacts区域，列出本次构建产出的全部文件及大小：

直接点击任意外观为方块图标的 artifact 名称即可下载（下载的是压缩归档）。原文档特别提醒：如果点击没有反应或无法下载，请确认自己已登录 GitHub 账号——下载 artifact 是要求登录的。

结合 Build.yml 中的上传配置，各 artifact 与目标平台的对应关系如下，可按需挑选：

版本后缀格式为v<主.次.修订>-<构建时间戳>（如截图中的v1.5.1-2024-03-01-08-26-39），固件 artifact 中额外带有hw-rev-B这类硬件修订号（来自 Makefile 的HW_REVISION宏）。

注意事项与补充说明

1. 稳定性预期：每日构建对应 master 分支的任意中间状态，文档原文即提醒"be prepared to find some unfinished things"。对生产测量场景，建议优先使用 Release 页面的正式发布版（由 Release_tag_stable.yml 在推送vX.Y.Z格式 tag 时自动上传到 Release，产物命名与每日构建一致但不带时间戳，且按 tag 归档、长期可下载）。
2. artifact 有保存期限：GitHub Actions 的 artifact 有默认保留期，较旧的 commit 构建产物可能已被自动清理，届时只能选择较新的 commit。
3. run 数量可能与文档略有出入：文档描述为"每个 commit 触发两次 run"（Build + 测试）。从 workflow 目录结构看，仓库还存在 HIL_Tests.yml（在master/HIL_actions分支推送时于树莓派自托管 runner 上编译 GUI 与固件并运行 Integrationtest.py 硬件在环测试）以及按 tag 触发的 Release workflow，个别时点 Actions 列表中的 run 数量可能多于两次，此时认准Buildworkflow 即可。
4. 验证固件版本：若使用了固件 artifact，集成测试 TestUpdate.py 展示了官方校验方式——通过 SCPI 命令DEV:UPDATE刷入combined.vnafw，再查询DEV:INF:FWREVISION?与 Makefile 中的版本号比对，读者可参照此法确认刷入的版本。

小结

下载 LibreVNA 每日构建的正确路径是：Actions 标签页 → 找到目标 commit 中 build 编号更高的一条 run → 确认其为Build.yml（含多 job 且有 artifact，而非无产物的Test.yml）→ 在页面底部 Artifacts 区点击对应平台的条目下载（需登录）。产物命名与内容均可在 Build.yml 与 AssembleFirmware.py 中逐行核对：GUI 版本号取自源码中的FW_MAJOR/FW_MINOR/FW_PATCH宏并附加构建时间戳，固件 artifact 则由 FPGA 位流与 MCU 固件经 24 字节头部加 CRC32 的组合方式打包为combined.vnafw。掌握这套定位与核验方法后，你可以随时把 master 分支的最新改动跑在自己的设备与 PC 上。

• 硬件开发
• 嵌入式
• 科研