如何配置 GitHub Actions 自动编译发布 Rust 跨平台二进制文件

配置 GitHub Actions 自动编译发布 Rust 跨平台二进制文件，最推荐的做法是使用矩阵策略（matrix strategy）在 ubuntu-latest、windows-latest 和 macos-latest 上分别运行 cargo build。风险边界在于 Linux 环境下 glibc 版本兼容性，生产环境建议优先编译 musl 静态链接二进制文件。

先说结论：通过 GitHub Actions 矩阵构建配合 action-gh-release 插件，可实现多平台自动化发布。

适合开源项目持续集成与自动打标
先准备 GitHub Token 写权限与 workflow 文件
验收需下载各平台产物运行验证

命令速用版

name: Release
on:
  push:
    tags:
      - 'v*'
jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - run: cargo build `--release`
      - uses: softprops/action-gh-release@v1
        with:
          files: target/release/your_binary_name

为什么会这样

CI 环境消除本地开发机器与生产环境的差异。Rust 跨平台编译依赖目标操作系统的链接器，GitHub Actions 提供的虚拟机预装了各平台标准构建工具链。

分步处理

第一步在仓库根目录创建 .github/workflows/release.yml 文件。第二步配置 matrix 策略覆盖目标操作系统列表。第三步调用 rust-toolchain 动作安装稳定版 Rust。第四步执行 cargo build `--release` 生成二进制文件。第五步使用 action-gh-release 将产物上传至 GitHub Releases 页面。

怎么验证是否生效

推送符合规则的 tag 后检查 Actions 面板状态是否为绿色。进入仓库 Releases 页面确认各平台二进制文件已上传。下载对应系统文件并在本地终端运行 `--version` 确认版本信息。

如何配置 GitHub Actions 自动编译发布 Rust 跨平台二进制文件

常见坑

Linux 默认编译产物依赖 glibc，在旧版系统可能无法运行，建议交叉编译至 x86_64-unknown-linux-musl。Windows 构建可能生成 pdb 调试文件，发布前需确认是否包含。macOS 若涉及 GUI 需处理签名公证，纯命令行工具通常无需额外配置。Cargo 依赖下载耗时较长，建议配置 actions/cache 缓存 registry 与 git 目录。

常见问题

如何生成 Linux 静态链接二进制文件

安装 musl 工具链并将 target 设置为 x86_64-unknown-linux-musl。在 workflow 中增加 steps 安装 musl-tools 并使用 cargo build `--target` 命令。

如何控制发布触发条件

在 workflow 文件的 on 字段中配置 push tags 或 release 事件。仅当推送匹配 v* 格式的标签时触发构建流程。

如何加速 GitHub Actions 构建

使用 actions/cache 动作缓存 Cargo 注册表与构建目标目录。公开资料中没有看到可靠的量化数据，但通常能显著减少依赖下载时间。

参考来源

GitHub Actions Documentation, "Understanding GitHub Actions", https://docs.github.com/en/actions
dtolnay/rust-toolchain, "GitHub Repository", https://github.com/dtolnay/rust-toolchain
softprops/action-gh-release, "GitHub Repository", https://github.com/softprops/action-gh-release