本文将介绍如何使用 GitHub Actions 为 Rust 项目实现跨平台自动化编译和发布，无需手动在不同操作系统上编译。
目录
背景
在开发 Rust 项目时，我们经常遇到这样的问题：
- 🤔 在 macOS 上开发，但用户需要 Windows 版本
- 😓 交叉编译配置复杂，容易出错
- 😫 需要在多个平台上手动编译和测试
- 📦 发布新版本时需要手动上传多个平台的文件
GitHub Actions 可以完美解决这些问题！
为什么需要 GitHub Actions
传统方式的问题
问题1：跨平台编译困难
# 在 macOS 上编译只能得到 macOS 版本
cargo build --release
# 输出：target/release/my_app (macOS only)
# Windows 用户无法直接使用！问题2：交叉编译配置复杂
# 需要安装额外工具
rustup target add x86_64-pc-windows-gnu
brew install mingw-w64
# 配置文件
# 创建 .cargo/config.toml ...
# 编译
cargo build --release --target x86_64-pc-windows-gnu
# 还可能遇到各种链接错误 😫GitHub Actions 的优势
✅ 自动化：推送 tag 自动构建所有平台
✅ 免费：公开仓库无限制使用
✅ 专业：在真实的操作系统上编译，不是模拟
✅ 简单：一次配置，永久使用
✅ 可靠：每次构建环境都是干净的
快速开始
1. 创建 Workflow 文件
在项目根目录创建 .github/workflows/build.yml：
name: Build and Release
on:
push:
tags:
- 'v*' # 当推送 v1.0.0 这样的 tag 时触发
jobs:
build:
name: Build - ${{ matrix.platform.os_name }}
runs-on: ${{ matrix.platform.os }}
strategy:
fail-fast: false
matrix:
platform:
- os_name: Windows-x86_64
os: windows-latest
target: x86_64-pc-windows-msvc
bin: my_app.exe
name: my_app-windows-x64.exe
- os_name: macOS-x86_64
os: macOS-latest
target: x86_64-apple-darwin
bin: my_app
name: my_app-macos-x64
- os_name: Linux-x86_64
os: ubuntu-latest
target: x86_64-unknown-linux-gnu
bin: my_app
name: my_app-linux-x64
steps:
- uses: actions/checkout@v4
- name: Build
uses: houseabsolute/actions-rust-cross@v0
with:
target: ${{ matrix.platform.target }}
args: "--release"
- name: Rename binary
run: |
cd target/${{ matrix.platform.target }}/release
mv ${{ matrix.platform.bin }} ${{ matrix.platform.name }}
shell: bash
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: ${{ matrix.platform.name }}
path: target/${{ matrix.platform.target }}/release/${{ matrix.platform.name }}
release:
needs: build
runs-on: ubuntu-latest
steps:
- name: Download all artifacts
uses: actions/download-artifact@v4
with:
path: artifacts
- name: Create Release
uses: softprops/action-gh-release@v1
with:
files: artifacts/**/*
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}2. 修改配置
将上面配置中的 my_app 改为你的项目名称：
bin: my_app.exe→bin: your_project_name.exename: my_app-windows-x64.exe→name: your_project_name-windows-x64.exe
3. 推送配置文件
git add .github/workflows/build.yml
git commit -m "feat: 添加 GitHub Actions 自动化构建"
git push4. 创建并推送 Tag
# 创建 tag
git tag v1.0.0 -m "First release"
# 推送 tag（这会触发构建）
git push origin v1.0.05. 查看构建进度
- 访问你的 GitHub 仓库
- 点击顶部 Actions 标签
- 查看构建进度
6. 下载编译好的文件
构建完成后：
- 访问仓库的 Releases 页面
- 找到刚创建的 v1.0.0 版本
- 下载对应平台的文件
完整配置详解
Workflow 触发条件
on:
push:
tags:
- 'v*' # 匹配 v1.0.0, v2.1.3 等格式的 tag其他常见触发方式：
# 每次推送到 main 分支时构建
on:
push:
branches: [ main ]
# PR 时构建测试
on:
pull_request:
branches: [ main ]
# 组合使用
on:
push:
branches: [ main ]
tags: [ 'v*' ]
pull_request:
branches: [ main ]构建矩阵（Matrix）
strategy:
fail-fast: false # 一个平台失败不影响其他平台
matrix:
platform:
- os_name: Windows-x86_64
os: windows-latest # GitHub 提供的 Windows 环境
target: x86_64-pc-windows-msvc # Rust 目标平台
bin: my_app.exe # 可执行文件名
name: my_app-windows-x64.exe # 发布时的文件名支持的平台：
| 平台 | os | target | 说明 |
|---|---|---|---|
| Windows 64位 | windows-latest | x86_64-pc-windows-msvc | 推荐 |
| macOS Intel | macOS-latest | x86_64-apple-darwin | Intel 芯片 |
| macOS Apple Silicon | macOS-latest | aarch64-apple-darwin | M1/M2 芯片 |
| Linux 64位 | ubuntu-latest | x86_64-unknown-linux-gnu | 最通用 |
构建步骤详解
1. 检出代码
- uses: actions/checkout@v4作用：从 Git 仓库拉取代码
2. 编译项目
- name: Build
uses: houseabsolute/actions-rust-cross@v0
with:
target: ${{ matrix.platform.target }}
args: "--release"作用：使用 cross 工具为目标平台编译
3. 重命名文件
- name: Rename binary
run: |
cd target/${{ matrix.platform.target }}/release
mv ${{ matrix.platform.bin }} ${{ matrix.platform.name }}
shell: bash作用：将 my_app.exe 重命名为 my_app-windows-x64.exe
4. 上传产物
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: ${{ matrix.platform.name }}
path: target/${{ matrix.platform.target }}/release/${{ matrix.platform.name }}作用：上传编译好的文件，供下一步使用
Release 任务
release:
needs: build # 等待所有平台构建完成
runs-on: ubuntu-latest
steps:
- name: Download all artifacts
uses: actions/download-artifact@v4
with:
path: artifacts
- name: Create Release
uses: softprops/action-gh-release@v1
with:
files: artifacts/**/*
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}作用：
- 下载所有平台的编译产物
- 创建 GitHub Release
- 上传所有文件到 Release
发布流程
标准发布流程
# 1. 开发并测试你的功能
git add .
git commit -m "feat: 添加新功能"
# 2. 推送代码（不会触发构建）
git push
# 3. 创建 tag（语义化版本）
git tag v1.0.0 -m "Release v1.0.0"
# 4. 推送 tag（触发构建）
git push origin v1.0.0
# 5. 等待 3-5 分钟，构建完成
# 6. 访问 Releases 页面查看版本号规范
遵循 语义化版本：
v主版本号.次版本号.修订号
v1.0.0 - 首次发布
v1.1.0 - 添加新功能
v1.1.1 - 修复 bug
v2.0.0 - 重大更新（不兼容的改动）示例：
# 修复 bug
git tag v1.0.1 -m "fix: 修复下载失败的问题"
git push origin v1.0.1
# 添加新功能
git tag v1.1.0 -m "feat: 添加多线程下载功能"
git push origin v1.1.0
# 重大更新
git tag v2.0.0 -m "feat!: 重构核心架构，不兼容 v1.x"
git push origin v2.0.0带详细说明的 Release
git tag -a v1.0.0 -m "
v1.0.0 - 2025-01-28
新功能：
- ✨ 支持多清晰度视频下载
- ✨ 自动无水印处理
- ✨ 支持新链接格式
改进：
- 🚀 下载速度提升 50%
- 🎨 优化了命令行界面
修复：
- 🐛 修复 Unicode 解码问题
- 🐛 修复部分链接无法识别的问题
"
git push origin v1.0.0常见问题
Q1: 构建失败怎么办？
查看日志：
- 进入 Actions 页面
- 点击失败的任务
- 展开错误的步骤查看详细日志
常见错误：
错误1：找不到 Cargo.toml
Error: Could not find Cargo.toml原因：项目根目录不对
解决：确保 .github/workflows/build.yml 和 Cargo.toml 在同一层级
错误2：依赖版本过时
deprecated version of 'actions/upload-artifact: v3'解决：升级到最新版本
- uses: actions/upload-artifact@v4 # v3 → v4错误3：编译错误
error: could not compile `my_app`解决：先在本地确保 cargo build --release 能成功
Q2: 如何测试 workflow？
方法1：推送到分支测试
on:
push:
branches: [ test-ci ] # 创建测试分支git checkout -b test-ci
git push origin test-ci方法2：手动触发
on:
workflow_dispatch: # 允许手动触发在 Actions 页面点击 "Run workflow" 按钮
Q3: 构建太慢怎么办？
优化1：使用缓存
- name: Cache cargo registry
uses: actions/cache@v3
with:
path: ~/.cargo/registry
key: ${{ runner.os }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
- name: Cache cargo index
uses: actions/cache@v3
with:
path: ~/.cargo/git
key: ${{ runner.os }}-cargo-index-${{ hashFiles('**/Cargo.lock') }}
- name: Cache cargo build
uses: actions/cache@v3
with:
path: target
key: ${{ runner.os }}-cargo-build-target-${{ hashFiles('**/Cargo.lock') }}优化2：减少构建平台
如果用户主要是 Windows，可以只构建 Windows 版本：
matrix:
platform:
- os_name: Windows-x86_64
os: windows-latest
target: x86_64-pc-windows-msvc
bin: my_app.exe
name: my_app-windows-x64.exeQ4: 如何支持 Apple Silicon (M1/M2)?
添加 ARM 架构的 macOS：
- os_name: macOS-ARM64
os: macOS-latest
target: aarch64-apple-darwin
bin: my_app
name: my_app-macos-arm64Q5: GitHub Actions 免费吗？
公开仓库：✅ 完全免费，无限制
私有仓库：
- 免费账户：2000 分钟/月
- Pro 账户：3000 分钟/月
- Team/Enterprise：更多配额
每次构建耗时：约 3-5 分钟（三个平台）
最佳实践
1. 只在发布时构建（推荐）
on:
push:
tags:
- 'v*'优点：
- 节省 Actions 配额
- Release 页面更清晰
- 只有稳定版本才对外发布
2. 平时推送也构建（适合持续集成）
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]优点：
- 及时发现编译问题
- 确保代码质量
缺点：
- 消耗更多 Actions 时间
3. 组合使用（最灵活）
on:
push:
branches: [ main ] # 推送：只构建，不发布
tags: [ 'v*' ] # Tag：构建并发布
pull_request:
branches: [ main ] # PR：构建测试4. 添加徽章（Badge）
在 README.md 中添加构建状态徽章：
效果：
5. 自动生成 Changelog
使用 git-cliff 自动生成更新日志：
- name: Generate Changelog
uses: orhun/git-cliff-action@v2
with:
config: cliff.toml
args: --latest --strip all
env:
OUTPUT: CHANGELOG.md6. 发布前自动测试
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run tests
run: cargo test --all-features
build:
needs: test # 测试通过后才构建
# ... 构建配置完整项目示例
项目结构
my_rust_project/
├── .github/
│ └── workflows/
│ └── build.yml # CI/CD 配置
├── src/
│ └── main.rs
├── Cargo.toml
├── Cargo.lock
└── README.md完整的 build.yml
name: Build and Release
on:
push:
tags:
- 'v*'
jobs:
test:
name: Test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run tests
run: cargo test --all-features
build:
name: Build - ${{ matrix.platform.os_name }}
needs: test
runs-on: ${{ matrix.platform.os }}
strategy:
fail-fast: false
matrix:
platform:
- os_name: Windows-x86_64
os: windows-latest
target: x86_64-pc-windows-msvc
bin: my_app.exe
name: my_app-windows-x64.exe
- os_name: macOS-x86_64
os: macOS-latest
target: x86_64-apple-darwin
bin: my_app
name: my_app-macos-x64
- os_name: macOS-ARM64
os: macOS-latest
target: aarch64-apple-darwin
bin: my_app
name: my_app-macos-arm64
- os_name: Linux-x86_64
os: ubuntu-latest
target: x86_64-unknown-linux-gnu
bin: my_app
name: my_app-linux-x64
steps:
- uses: actions/checkout@v4
- name: Cache cargo registry
uses: actions/cache@v3
with:
path: ~/.cargo/registry
key: ${{ runner.os }}-cargo-registry-${{ hashFiles('**/Cargo.lock') }}
- name: Cache cargo index
uses: actions/cache@v3
with:
path: ~/.cargo/git
key: ${{ runner.os }}-cargo-index-${{ hashFiles('**/Cargo.lock') }}
- name: Build
uses: houseabsolute/actions-rust-cross@v0
with:
target: ${{ matrix.platform.target }}
args: "--release"
- name: Rename binary
run: |
cd target/${{ matrix.platform.target }}/release
mv ${{ matrix.platform.bin }} ${{ matrix.platform.name }}
shell: bash
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: ${{ matrix.platform.name }}
path: target/${{ matrix.platform.target }}/release/${{ matrix.platform.name }}
release:
name: Create Release
needs: build
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Download all artifacts
uses: actions/download-artifact@v4
with:
path: artifacts
- name: Create Release
uses: softprops/action-gh-release@v1
with:
files: artifacts/**/*
body: |
## 下载说明
请根据你的操作系统下载对应的文件：
- **Windows 用户**：下载 `my_app-windows-x64.exe`
- **macOS Intel 用户**：下载 `my_app-macos-x64`
- **macOS M1/M2 用户**：下载 `my_app-macos-arm64`
- **Linux 用户**：下载 `my_app-linux-x64`
## 使用方法
下载后直接运行即可，无需安装其他依赖。
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}进阶技巧
1. 条件执行
只在主分支发布：
release:
if: github.ref == 'refs/heads/main'
# ...2. 多个 Workflow
可以创建多个 workflow 文件：
.github/workflows/
├── test.yml # 每次推送都测试
├── build.yml # 每次推送都构建
└── release.yml # 只在 tag 时发布3. 使用 secrets
存储敏感信息：
env:
API_KEY: ${{ secrets.MY_API_KEY }}在仓库设置中添加 secrets：
Settings → Secrets → Actions → New repository secret
4. 定时任务
每周自动构建测试：
on:
schedule:
- cron: '0 0 * * 0' # 每周日 00:00总结
使用 GitHub Actions 的好处：
✅ 自动化：推送 tag 自动编译发布
✅ 跨平台：一次配置，支持 Windows/macOS/Linux
✅ 专业：在真实系统上编译，不是交叉编译
✅ 免费：公开仓库无限制使用
✅ 可靠：每次都是干净环境，可重复构建
✅ 简单：无需本地安装多平台工具链
快速开始检查清单
- [ ] 创建
.github/workflows/build.yml文件 - [ ] 修改配置中的项目名称
- [ ] 提交并推送配置文件
- [ ] 创建并推送第一个 tag：
git tag v1.0.0 && git push origin v1.0.0 - [ ] 查看 Actions 页面的构建进度
- [ ] 在 Releases 页面下载编译好的文件
参考资源
最后更新: 2025-01-28
作者: 梁予安
许可: MIT License
