distributing-tauri-for-ios

面向 iOS 分发 Tauri 应用

本技能涵盖将 Tauri v2 应用分发到 Apple iOS App Store 的完整流程。

前提条件

分发 Tauri iOS 应用前，请确保：

1. macOS 开发机器（iOS 构建所必需）
2. 已安装包含 iOS SDK 的 Xcode
3. 已加入 Apple Developer Program（每年 99 美元）
4. 已为 Tauri 项目初始化 iOS（tauri ios init）

加入 Apple Developer Program

在 developer.apple.com/programs 加入：

1. 使用 Apple ID 登录
2. 接受 Apple Developer Agreement
3. 完成注册（个人或组织）
4. 等待审核通过（通常需要 24–48 小时）

配置 Bundle Identifier

Bundle Identifier 必须唯一，并且在所有配置中保持一致。

tauri.conf.json

{
  "identifier": "com.yourcompany.yourapp",
  "version": "1.0.0",
  "bundle": {
    "iOS": {
      "bundleVersion": "1"
    }
  }
}

配置说明：

• identifier：反向域名格式，必须与 App Store Connect 中的内容一致
• version：将成为 CFBundleShortVersionString（用户可见的版本号）
• bundleVersion：将成为 CFBundleVersion（构建号，每次上传时都必须递增）

在 App Store Connect 中注册 Bundle ID

1. 前往 Certificates, Identifiers & Profiles
2. 点击“+”注册新的标识符
3. 选择“App IDs”，然后选择“App”
4. 输入描述和与 tauri.conf.json 匹配的显式 Bundle ID
5. 选择所需功能
6. 点击“Register”

设置代码签名

创建证书

分发证书（App Store 必需）：

1. 在 macOS 上打开“钥匙串访问”
2. 选择“钥匙串访问”>“证书助理”>“从证书颁发机构请求证书”
3. 输入电子邮件，选择“存储到磁盘”
4. 前往 Certificates
5. 点击“+”并选择“Apple Distribution”
6. 上传证书签名请求
7. 下载并双击安装

创建 Provisioning Profile

App Store 分发配置文件：

1. 前往 Profiles
2. 点击“+”创建新的配置文件
3. 在“Distribution”下选择“App Store Connect”
4. 选择你的 App ID
5. 选择你的分发证书
6. 为配置文件命名并生成
7. 下载 .mobileprovision 文件

安装 Provisioning Profile

# Copy to Xcode provisioning profiles directory
cp ~/Downloads/YourApp_AppStore.mobileprovision \
   ~/Library/MobileDevice/Provisioning\ Profiles/

也可以双击该文件自动安装。

配置 Xcode 项目

在 Xcode 中打开 Tauri iOS 项目：

tauri ios build --open

在 Xcode 中配置签名

1. 在导航器中选择项目
2. 选择你的应用目标
3. 前往“Signing & Capabilities”选项卡
4. 取消勾选“Automatically manage signing”以进行手动控制
5. 选择你的 Team
6. 选择 App Store Provisioning Profile

所需功能

根据应用需求添加功能：

功能	需要时机
推送通知	使用 APNs 时
后台模式	执行后台任务时
App Groups	在扩展之间共享数据时
关联域名	使用通用链接时

配置 Info.plist

位于 src-tauri/gen/apple/[AppName]_iOS/Info.plist：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleDisplayName</key>
    <string>Your App Name</string>
    <key>CFBundleName</key>
    <string>YourApp</string>
    <key>CFBundleIdentifier</key>
    <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
    <key>CFBundleVersion</key>
    <string>$(CURRENT_PROJECT_VERSION)</string>
    <key>CFBundleShortVersionString</key>
    <string>$(MARKETING_VERSION)</string>
    <key>UILaunchStoryboardName</key>
    <string>LaunchScreen</string>
    <key>UISupportedInterfaceOrientations</key>
    <array>
        <string>UIInterfaceOrientationPortrait</string>
        <string>UIInterfaceOrientationLandscapeLeft</string>
        <string>UIInterfaceOrientationLandscapeRight</string>
    </array>
    <key>NSCameraUsageDescription</key>
    <string>This app requires camera access for...</string>
    <key>NSPhotoLibraryUsageDescription</key>
    <string>This app requires photo library access for...</string>
</dict>
</plist>

必需的用途说明（仅当应用使用以下功能时才添加）：

• NSCameraUsageDescription：相机访问权限
• NSPhotoLibraryUsageDescription：照片图库
• NSLocationWhenInUseUsageDescription：位置服务
• NSMicrophoneUsageDescription：麦克风访问权限

应用图标

从源图像生成 iOS 应用图标（建议使用 1024x1024）：

tauri icon /path/to/app-icon.png --ios-color '#ffffff'

这会在 src-tauri/gen/apple/Assets.xcassets/AppIcon.appiconset/ 中生成所有必需尺寸的图标。

构建 App Store 版本

命令行构建

# Build IPA for App Store Connect
tauri ios build --export-method app-store-connect

IPA 生成路径：

src-tauri/gen/apple/build/arm64/[AppName].ipa

构建选项

# Build with specific target
tauri ios build --target aarch64-apple-ios --export-method app-store-connect

# Build in release mode (default for export-method)
tauri ios build --release --export-method app-store-connect

# Build and open in Xcode for manual archive
tauri ios build --open

通过 Xcode 归档（替代方案）

1. 打开项目：tauri ios build --open
2. 选择“Any iOS Device”作为目标设备
3. Product > Archive
4. Window > Organizer，查看归档
5. 点击“Distribute App”
6. 选择“App Store Connect”
7. 按照向导操作

App Store Connect API 密钥设置

创建用于自动上传的 API 密钥：

1. 前往 App Store Connect > Users and Access
2. 选择“Integrations”标签页
3. 点击“App Store Connect API”，然后点击“+”
4. 为密钥命名，并选择“Admin”或“Developer”角色
5. 点击“Generate”
6. 下载 .p8 文件（仅可下载一次）
7. 记下 Key ID 和 Issuer ID

存储 API 密钥

# Create directory
mkdir -p ~/.appstoreconnect/private_keys

# Move the key file (rename to include Key ID)
mv ~/Downloads/AuthKey_XXXXXXXXXX.p8 ~/.appstoreconnect/private_keys/

# Alternative location
mkdir -p ~/private_keys
mv ~/Downloads/AuthKey_XXXXXXXXXX.p8 ~/private_keys/

环境变量（可选）

export APPLE_API_KEY_ID="XXXXXXXXXX"
export APPLE_API_ISSUER="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

上传到 App Store Connect

使用 altool

xcrun altool --upload-app \
  --type ios \
  --file "src-tauri/gen/apple/build/arm64/YourApp.ipa" \
  --apiKey "$APPLE_API_KEY_ID" \
  --apiIssuer "$APPLE_API_ISSUER"

使用 Transporter 应用

1. 从 Mac App Store 下载 Transporter
2. 使用 Apple ID 登录
3. 拖放 IPA 文件
4. 点击“Deliver”

使用 Xcode Organizer

1. Window > Organizer
2. 选择归档
3. 点击“Distribute App”
4. 选择“App Store Connect”
5. 选择“Upload”或“Export”
6. 按照提示操作

TestFlight Beta 测试

上传处理完成后（通常需要 15-30 分钟）：

内部测试

1. App Store Connect > Your App > TestFlight
2. 添加内部测试人员（最多 100 人，必须是 App Store Connect 用户）
3. 测试人员会收到电子邮件邀请

外部测试

1. 创建测试组
2. 将构建版本添加到该组
3. 提交 Beta App Review（外部测试人员必须经过此审核）
4. 添加外部测试人员（最多 10,000 人）
5. 测试人员通过 TestFlight 应用安装

App Store 提交

在 App Store Connect 中创建应用

1. 前往 App Store Connect
2. My Apps > “+” > New App
3. 选择 iOS 平台
4. 输入应用名称、主要语言、Bundle ID 和 SKU
5. 点击“Create”

准备 App Store 页面

所需素材：

素材	规格
屏幕截图	6.7"（1290x2796）、6.5"（1284x2778）、5.5"（1242x2208）
应用图标	1024x1024 PNG（无 Alpha 通道）
描述	最多 4000 个字符
关键词	最多 100 个字符
支持 URL	必填
隐私政策 URL	必填

应用隐私

完成应用隐私问卷：

1. App Store Connect > Your App > App Privacy
2. 回答有关数据收集的问题
3. 指明收集的数据类型
4. 说明数据使用目的

提交审核

1. 在 App Store Connect 中选择构建版本
2. 填写所有必需的元数据
3. 回答出口合规性问题
4. 点击“Submit for Review”

审核通常需要 24-48 小时。

常见问题与解决方案

代码签名错误

“No signing certificate found”

# List available certificates
security find-identity -v -p codesigning

# Verify certificate is valid
security find-certificate -c "Apple Distribution" -p

“Provisioning profile doesn't match”

• 确保所有位置的 Bundle ID 完全一致
• 如果证书有变更，请重新生成配置描述文件

构建失败

“Unsupported architecture”

# Ensure building for correct target
tauri ios build --target aarch64-apple-ios --export-method app-store-connect

“Missing entitlements”

• 检查 Xcode 中的功能是否与 App ID 功能匹配
• 功能变更后，重新生成配置描述文件

上传错误

“Invalid binary”

• 确保正确设置最低 iOS 版本
• 确认所有必需的图标均已提供
• 检查 Info.plist 是否包含必需的键

“Missing compliance” 如果未使用加密，请添加到 Info.plist：

<key>ITSAppUsesNonExemptEncryption</key>
<false/>

CI/CD 集成

GitHub Actions 示例

name: iOS Release

on:
  push:
    tags:
      - 'v*'

jobs:
  build-ios:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Rust
        uses: dtolnay/rust-action@stable
        with:
          targets: aarch64-apple-ios

      - name: Install dependencies
        run: npm ci

      - name: Install certificate
        env:
          CERTIFICATE_BASE64: ${{ secrets.APPLE_CERTIFICATE_BASE64 }}
          CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
        run: |
          CERTIFICATE_PATH=$RUNNER_TEMP/certificate.p12
          KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db

          echo -n "$CERTIFICATE_BASE64" | base64 --decode > $CERTIFICATE_PATH

          security create-keychain -p "" $KEYCHAIN_PATH
          security set-keychain-settings -lut 21600 $KEYCHAIN_PATH
          security unlock-keychain -p "" $KEYCHAIN_PATH

          security import $CERTIFICATE_PATH -P "$CERTIFICATE_PASSWORD" \
            -A -t cert -f pkcs12 -k $KEYCHAIN_PATH

          security list-keychain -d user -s $KEYCHAIN_PATH

      - name: Install provisioning profile
        env:
          PROVISIONING_PROFILE_BASE64: ${{ secrets.PROVISIONING_PROFILE_BASE64 }}
        run: |
          PP_PATH=$RUNNER_TEMP/profile.mobileprovision
          echo -n "$PROVISIONING_PROFILE_BASE64" | base64 --decode > $PP_PATH
          mkdir -p ~/Library/MobileDevice/Provisioning\ Profiles
          cp $PP_PATH ~/Library/MobileDevice/Provisioning\ Profiles/

      - name: Build iOS
        run: npm run tauri ios build -- --export-method app-store-connect

      - name: Upload to App Store Connect
        env:
          APPLE_API_KEY_ID: ${{ secrets.APPLE_API_KEY_ID }}
          APPLE_API_ISSUER: ${{ secrets.APPLE_API_ISSUER }}
          APPLE_API_KEY: ${{ secrets.APPLE_API_KEY }}
        run: |
          mkdir -p ~/.appstoreconnect/private_keys
          echo "$APPLE_API_KEY" > ~/.appstoreconnect/private_keys/AuthKey_$APPLE_API_KEY_ID.p8

          xcrun altool --upload-app --type ios \
            --file src-tauri/gen/apple/build/arm64/*.ipa \
            --apiKey $APPLE_API_KEY_ID \
            --apiIssuer $APPLE_API_ISSUER

版本管理

递增版本号

每次提交到 App Store 时，都应按需递增版本号：

{
  "version": "1.0.0",
  "bundle": {
    "iOS": {
      "bundleVersion": "1"
    }
  }
}

• version：用户可见变更时递增（1.0.0 -> 1.0.1 或 1.1.0）
• bundleVersion：每次上传都必须递增（1 -> 2 -> 3）

版本脚本示例

#!/bin/bash
# increment-build.sh
CONFIG="src-tauri/tauri.conf.json"
CURRENT=$(jq -r '.bundle.iOS.bundleVersion' $CONFIG)
NEW=$((CURRENT + 1))
jq ".bundle.iOS.bundleVersion = \"$NEW\"" $CONFIG > tmp.json && mv tmp.json $CONFIG
echo "Bundle version incremented to $NEW"

参考链接

• Apple Developer Program
• App Store Connect
• App Store 审核指南
• Tauri iOS 文档
• Tauri 分发指南