使用 GitHub Actions 自动编译 OpenWrt 固件：配置与验证流程

OpenWrt 固件编译最容易出问题的地方，不是最后那条 make 命令，而是前面的目标设备和配置。型号选错，编译出来的文件即使成功生成，也不能刷进设备。把配置和构建过程放进 GitHub 仓库后，至少可以把这些选择记录下来，换机器也能重跑。

先确认设备对应的目标

先在路由器后台或 SSH 中确认设备型号、架构和当前版本。不要只凭外壳型号猜 target；同一系列设备可能使用不同硬件版本。

源码可以从 OpenWrt 官方仓库开始：

git clone https://github.com/openwrt/openwrt.git
cd openwrt
git branch -a
git checkout openwrt-24.10

分支名称应以仓库实际存在的分支为准。稳定分支和开发分支的配置项可能不同，教程中的版本号也不要原样照搬到未来环境。

更新 feeds 并选择软件包

./scripts/feeds update -a
./scripts/feeds install -a
make menuconfig

在菜单中先选正确的 Target System、Subtarget 和设备 Profile，再考虑添加软件包。路由器的闪存空间很有限，看到什么都选进去，最后往往会在打包阶段因为空间不够失败。

退出菜单并保存后，可以先生成默认配置：

make defconfig

建议把最终的 .config 保存到自己的仓库。它比一张菜单截图更容易复用，也方便比较两次构建到底改了哪些选项。

把构建放进 GitHub Actions

一个最小工作流可以手动触发，然后逐步加入缓存和产物上传。下面的片段只展示流程，实际项目还需要放入自己的配置文件：

name: Build OpenWrt

on:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Prepare feeds
        run: |
          ./scripts/feeds update -a
          ./scripts/feeds install -a
          make defconfig
      - name: Build firmware
        run: make -j$(nproc) V=s

正式使用时还应上传 bin/targets 下的固件文件和校验值，否则构建结束后只剩一条“成功”记录，下载不到实际产物。编译时间较长时，可以再考虑缓存下载目录，但缓存配置错误也可能带来旧依赖，第一次运行不建议急着加。

刷机前不要省掉验证

构建完成后先列出产物，确认目标平台和设备 Profile：

find bin/targets -type f
sha256sum bin/targets/*/*/*

刷写前核对文件名、文件大小和校验值。第一次给设备刷自编译固件时，最好准备官方恢复固件，并提前确认恢复入口。升级过程中不要断电，也不要把其他型号的配置文件直接导入。

失败时先看哪儿

找不到软件包

先重新执行 feeds 更新和安装，再检查分支是否和教程一致。很多“软件包不存在”并不是包真的消失了，而是 feeds 没有更新。

镜像太大

回到 make menuconfig，删掉不必要的语言包、主题和调试工具。对闪存只有几 MB 的设备，每一个额外组件都可能影响最终镜像。

Actions 被系统终止

查看构建日志中是否出现内存不足、磁盘不足或超时。把并行度从 -j$(nproc) 调低，通常比盲目重试更容易定位问题。

把配置留下来

自动编译的价值不在于省掉一次命令，而在于下次还能得到相同结果。仓库里至少保留分支、工作流、.config、构建日期和产物校验值。设备升级前也留一份当前配置，出了问题才有回退依据。