Back to Details

building-tauri-with-github-actions

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Building Tauri Apps with GitHub Actions

使用GitHub Actions构建Tauri应用

This skill covers CI/CD pipeline configuration for Tauri applications using GitHub Actions and the official 
tauri-apps/tauri-action
.
本技能介绍如何使用GitHub Actions及官方
tauri-apps/tauri-action
配置Tauri应用的CI/CD流水线。

Overview

概述

GitHub Actions enables automated building, testing, and releasing of Tauri applications across Windows, macOS, and Linux platforms. The 
tauri-action
handles the complexity of cross-platform builds and release management.
GitHub Actions可实现Windows、macOS和Linux平台上Tauri应用的自动化构建、测试与发布。
tauri-action
负责处理跨平台构建与发布管理的复杂流程。

Workflow Triggers

工作流触发器

Push to Release Branch

推送到发布分支

yaml
name: 'publish'
on:
  workflow_dispatch:
  push:
    branches:
      - release
yaml
name: 'publish'
on:
  workflow_dispatch:
  push:
    branches:
      - release

Tag-Based Releases

基于标签的发布

yaml
name: 'publish'
on:
  push:
    tags:
      - 'app-v*'
yaml
name: 'publish'
on:
  push:
    tags:
      - 'app-v*'

Platform Matrix Configuration

平台矩阵配置

Standard Multi-Platform Matrix

标准多平台矩阵

yaml
jobs:
  publish-tauri:
    permissions:
      contents: write
    strategy:
      fail-fast: false
      matrix:
        include:
          - platform: 'macos-latest'
            args: '--target aarch64-apple-darwin'
          - platform: 'macos-latest'
            args: '--target x86_64-apple-darwin'
          - platform: 'ubuntu-22.04'
            args: ''
          - platform: 'windows-latest'
            args: ''

    runs-on: ${{ matrix.platform }}
yaml
jobs:
  publish-tauri:
    permissions:
      contents: write
    strategy:
      fail-fast: false
      matrix:
        include:
          - platform: 'macos-latest'
            args: '--target aarch64-apple-darwin'
          - platform: 'macos-latest'
            args: '--target x86_64-apple-darwin'
          - platform: 'ubuntu-22.04'
            args: ''
          - platform: 'windows-latest'
            args: ''

    runs-on: ${{ matrix.platform }}

With ARM Linux Support (Public Repos Only)

支持ARM Linux（仅公共仓库）

Add 
ubuntu-22.04-arm
to the matrix for native ARM64 Linux builds (public repositories only).
在矩阵中添加
ubuntu-22.04-arm
可实现原生ARM64 Linux构建（仅适用于公共仓库）。

Complete Workflow Example

完整工作流示例

yaml
name: 'publish'

on:
  workflow_dispatch:
  push:
    branches:
      - release

jobs:
  publish-tauri:
    permissions:
      contents: write
    strategy:
      fail-fast: false
      matrix:
        include:
          - platform: 'macos-latest'
            args: '--target aarch64-apple-darwin'
          - platform: 'macos-latest'
            args: '--target x86_64-apple-darwin'
          - platform: 'ubuntu-22.04'
            args: ''
          - platform: 'windows-latest'
            args: ''

    runs-on: ${{ matrix.platform }}
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies (Ubuntu only)
        if: matrix.platform == 'ubuntu-22.04'
        run: |
          sudo apt-get update
          sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: lts/*
          cache: 'npm'

      - name: Setup Rust toolchain
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: ${{ matrix.platform == 'macos-latest' && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}

      - name: Rust cache
        uses: swatinem/rust-cache@v2
        with:
          workspaces: './src-tauri -> target'

      - name: Install frontend dependencies
        run: npm ci

      - name: Build and release
        uses: tauri-apps/tauri-action@v0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tagName: app-v__VERSION__
          releaseName: 'App v__VERSION__'
          releaseBody: 'See the assets to download this version and install.'
          releaseDraft: true
          prerelease: false
          args: ${{ matrix.args }}
yaml
name: 'publish'

on:
  workflow_dispatch:
  push:
    branches:
      - release

jobs:
  publish-tauri:
    permissions:
      contents: write
    strategy:
      fail-fast: false
      matrix:
        include:
          - platform: 'macos-latest'
            args: '--target aarch64-apple-darwin'
          - platform: 'macos-latest'
            args: '--target x86_64-apple-darwin'
          - platform: 'ubuntu-22.04'
            args: ''
          - platform: 'windows-latest'
            args: ''

    runs-on: ${{ matrix.platform }}
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies (Ubuntu only)
        if: matrix.platform == 'ubuntu-22.04'
        run: |
          sudo apt-get update
          sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: lts/*
          cache: 'npm'

      - name: Setup Rust toolchain
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: ${{ matrix.platform == 'macos-latest' && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}

      - name: Rust cache
        uses: swatinem/rust-cache@v2
        with:
          workspaces: './src-tauri -> target'

      - name: Install frontend dependencies
        run: npm ci

      - name: Build and release
        uses: tauri-apps/tauri-action@v0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tagName: app-v__VERSION__
          releaseName: 'App v__VERSION__'
          releaseBody: 'See the assets to download this version and install.'
          releaseDraft: true
          prerelease: false
          args: ${{ matrix.args }}

Package Manager Variants

包管理器变体

pnpm

pnpm

yaml
- name: Setup pnpm
  uses: pnpm/action-setup@v4
  with:
    version: latest

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: lts/*
    cache: 'pnpm'

- name: Install frontend dependencies
  run: pnpm install
yaml
- name: Setup pnpm
  uses: pnpm/action-setup@v4
  with:
    version: latest

- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: lts/*
    cache: 'pnpm'

- name: Install frontend dependencies
  run: pnpm install

Yarn

Yarn

yaml
- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: lts/*
    cache: 'yarn'

- name: Install frontend dependencies
  run: yarn install --frozen-lockfile
yaml
- name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: lts/*
    cache: 'yarn'

- name: Install frontend dependencies
  run: yarn install --frozen-lockfile

Caching Strategies

缓存策略

Rust Artifact Caching

Rust工件缓存

yaml
- name: Rust cache
  uses: swatinem/rust-cache@v2
  with:
    workspaces: './src-tauri -> target'
yaml
- name: Rust cache
  uses: swatinem/rust-cache@v2
  with:
    workspaces: './src-tauri -> target'

Node.js Dependency Caching

Node.js依赖缓存

Configure via the 
cache
parameter in 
actions/setup-node@v4
: 
'npm'
, 
'yarn'
, or 
'pnpm'
.
通过
actions/setup-node@v4
中的
cache
参数配置：可选值为
'npm'
、
'yarn'
或
'pnpm'
。

Linux Dependencies

Linux依赖

Ubuntu requires WebKit and related libraries:
yaml
- name: Install dependencies (Ubuntu only)
  if: matrix.platform == 'ubuntu-22.04'
  run: |
    sudo apt-get update
    sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf
Ubuntu需要WebKit及相关库：
yaml
- name: Install dependencies (Ubuntu only)
  if: matrix.platform == 'ubuntu-22.04'
  run: |
    sudo apt-get update
    sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf

Release Automation

发布自动化

tauri-action Configuration

tauri-action配置

yaml
- uses: tauri-apps/tauri-action@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
    tagName: app-v__VERSION__
    releaseName: 'App v__VERSION__'
    releaseBody: 'See the assets to download this version and install.'
    releaseDraft: true
    prerelease: false
    args: ${{ matrix.args }}
yaml
- uses: tauri-apps/tauri-action@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
    tagName: app-v__VERSION__
    releaseName: 'App v__VERSION__'
    releaseBody: 'See the assets to download this version and install.'
    releaseDraft: true
    prerelease: false
    args: ${{ matrix.args }}

Version Placeholders

版本占位符

The action automatically replaces 
__VERSION__
with the app version from 
tauri.conf.json
.
该动作会自动将
__VERSION__
替换为
tauri.conf.json
中的应用版本。

Release Options

发布选项

OptionDescription
tagName
Git tag for the release (supports 
__VERSION__
placeholder)
releaseName
Display name for the release
releaseBody
Release notes content
releaseDraft
Create as draft release (
true
/
false
)
prerelease
Mark as prerelease (
true
/
false
)
选项描述
tagName
发布对应的Git标签（支持
__VERSION__
占位符）
releaseName
发布的显示名称
releaseBody
发布说明内容
releaseDraft
是否创建为草稿发布（
true
/
false
）
prerelease
是否标记为预发布版本（
true
/
false
）

Artifact Uploads

工件上传

Upload Build Artifacts Without Release

仅上传构建工件而不发布

yaml
- name: Build Tauri app
  uses: tauri-apps/tauri-action@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  id: tauri

- name: Upload artifacts
  uses: actions/upload-artifact@v4
  with:
    name: tauri-build-${{ matrix.platform }}
    path: src-tauri/target/release/bundle/
yaml
- name: Build Tauri app
  uses: tauri-apps/tauri-action@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  id: tauri

- name: Upload artifacts
  uses: actions/upload-artifact@v4
  with:
    name: tauri-build-${{ matrix.platform }}
    path: src-tauri/target/release/bundle/

GitHub Token Configuration

GitHub Token配置

The 
GITHUB_TOKEN
requires write permissions for release creation.
GITHUB_TOKEN
需要具备创建发布的写入权限。

Repository Settings

仓库设置

  1. Go to Settings > Actions > General
  2. Under "Workflow permissions"
  3. Select "Read and write permissions"
  4. Save
  1. 进入Settings > Actions > General
  2. 在“Workflow permissions”下
  3. 选择“Read and write permissions”
  4. 保存

Workflow Permissions

工作流权限

yaml
jobs:
  publish-tauri:
    permissions:
      contents: write
yaml
jobs:
  publish-tauri:
    permissions:
      contents: write

Non-Root Project Configuration

非根目录项目配置

For projects where Tauri is not at the repository root:
yaml
- uses: tauri-apps/tauri-action@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
    projectPath: './apps/desktop'
    tagName: app-v__VERSION__
    releaseName: 'App v__VERSION__'
当Tauri不在仓库根目录时：
yaml
- uses: tauri-apps/tauri-action@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
    projectPath: './apps/desktop'
    tagName: app-v__VERSION__
    releaseName: 'App v__VERSION__'

ARM Build Emulation (Alternative)

ARM构建模拟（替代方案）

For ARM builds in private repositories or when native ARM runners are unavailable:
yaml
jobs:
  build-arm:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build ARM64
        uses: pguyot/arm-runner-action@v2.6.5
        with:
          base_image: dietpi:rpi_armv8_bullseye
          commands: |
            apt-get update
            apt-get install -y curl build-essential libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf
            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
            source $HOME/.cargo/env
            curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
            apt-get install -y nodejs
            npm ci
            npm run tauri build
Note: ARM emulation builds take approximately one hour for fresh projects.
对于私有仓库或无法使用原生ARM运行器的情况，可使用ARM模拟：
yaml
jobs:
  build-arm:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build ARM64
        uses: pguyot/arm-runner-action@v2.6.5
        with:
          base_image: dietpi:rpi_armv8_bullseye
          commands: |
            apt-get update
            apt-get install -y curl build-essential libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf
            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
            source $HOME/.cargo/env
            curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
            apt-get install -y nodejs
            npm ci
            npm run tauri build
注意：ARM模拟构建对于新项目大约需要一小时。

Code Signing Integration

代码签名集成

macOS Signing Environment Variables

macOS签名环境变量

yaml
- uses: tauri-apps/tauri-action@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
    APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
    APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }}
    APPLE_ID: ${{ secrets.APPLE_ID }}
    APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
    APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
yaml
- uses: tauri-apps/tauri-action@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
    APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
    APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }}
    APPLE_ID: ${{ secrets.APPLE_ID }}
    APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
    APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}

Windows Signing Environment Variables

Windows签名环境变量

yaml
- uses: tauri-apps/tauri-action@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
    TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
yaml
- uses: tauri-apps/tauri-action@v0
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
    TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}

CI-Only Workflow (No Release)

仅CI工作流（无发布）

For pull request validation without creating releases:
yaml
name: 'CI Build'

on:
  pull_request:
    branches:
      - main

jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        include:
          - platform: 'macos-latest'
            args: '--target aarch64-apple-darwin'
          - platform: 'ubuntu-22.04'
            args: ''
          - platform: 'windows-latest'
            args: ''

    runs-on: ${{ matrix.platform }}
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies (Ubuntu only)
        if: matrix.platform == 'ubuntu-22.04'
        run: |
          sudo apt-get update
          sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: lts/*
          cache: 'npm'

      - name: Setup Rust toolchain
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: ${{ matrix.platform == 'macos-latest' && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}

      - name: Rust cache
        uses: swatinem/rust-cache@v2
        with:
          workspaces: './src-tauri -> target'

      - name: Install frontend dependencies
        run: npm ci

      - name: Build Tauri app
        run: npm run tauri build -- ${{ matrix.args }}
用于拉取请求验证，不创建发布：
yaml
name: 'CI Build'

on:
  pull_request:
    branches:
      - main

jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        include:
          - platform: 'macos-latest'
            args: '--target aarch64-apple-darwin'
          - platform: 'ubuntu-22.04'
            args: ''
          - platform: 'windows-latest'
            args: ''

    runs-on: ${{ matrix.platform }}
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies (Ubuntu only)
        if: matrix.platform == 'ubuntu-22.04'
        run: |
          sudo apt-get update
          sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: lts/*
          cache: 'npm'

      - name: Setup Rust toolchain
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: ${{ matrix.platform == 'macos-latest' && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}

      - name: Rust cache
        uses: swatinem/rust-cache@v2
        with:
          workspaces: './src-tauri -> target'

      - name: Install frontend dependencies
        run: npm ci

      - name: Build Tauri app
        run: npm run tauri build -- ${{ matrix.args }}

Troubleshooting

故障排除

Permission Denied for Release Creation

发布创建权限被拒绝

Ensure workflow has write permissions and verify repository settings allow Actions to create releases:
yaml
jobs:
  publish-tauri:
    permissions:
      contents: write
确保工作流具备写入权限，并验证仓库设置允许Actions创建发布：
yaml
jobs:
  publish-tauri:
    permissions:
      contents: write

Linux Build Failures

Linux构建失败

Verify all dependencies are installed with the Ubuntu dependency installation step.
通过Ubuntu依赖安装步骤确认所有依赖已安装。

macOS Target Not Found

macOS目标未找到

Ensure Rust targets are installed for cross-compilation:
yaml
- uses: dtolnay/rust-toolchain@stable
  with:
    targets: 'aarch64-apple-darwin,x86_64-apple-darwin'
确保已安装用于交叉编译的Rust目标：
yaml
- uses: dtolnay/rust-toolchain@stable
  with:
    targets: 'aarch64-apple-darwin,x86_64-apple-darwin'

Cache Not Working

缓存未生效

Verify the workspace path matches your project structure:
yaml
- uses: swatinem/rust-cache@v2
  with:
    workspaces: './src-tauri -> target'
确认工作区路径与项目结构匹配：
yaml
- uses: swatinem/rust-cache@v2
  with:
    workspaces: './src-tauri -> target'