distributing-tauri-for-android

分发 Tauri Android 应用

本指南涵盖准备和分发 Tauri v2 Android 应用的完整工作流，包括在 Google Play 商店发布。

先决条件

分发 Tauri Android 应用之前：

1. Play Console 账号：在 https://play.google.com/console/developers 创建开发者账号
2. Android SDK：确保已安装并配置 Android SDK
3. 代码签名：设置 Android 代码签名（keystore）
4. 已初始化 Tauri Android：如果尚未初始化，请运行 tauri android init

应用图标配置

初始化 Android 支持后，配置应用图标：

# npm
npm run tauri icon /path/to/app-icon.png

# yarn
yarn tauri icon /path/to/app-icon.png

# pnpm
pnpm tauri icon /path/to/app-icon.png

# cargo
cargo tauri icon /path/to/app-icon.png

这会生成 Android 所需的各种尺寸的图标。

构建配置

tauri.conf.json Android 设置

在 tauri.conf.json 中配置 Android 专属设置：

{
  "bundle": {
    "android": {
      "minSdkVersion": 24,
      "versionCode": 1
    }
  }
}

配置选项

选项	默认值	描述
minSdkVersion	24	最低 Android SDK 版本（Android 7.0）
versionCode	自动计算	Play Store 使用的整数版本代码

版本代码计算

Tauri 会根据应用版本自动计算版本代码：

versionCode = major * 1000000 + minor * 1000 + patch

示例：版本 1.2.3 会转换为版本代码 1002003

如果需要使用连续编号，可在 tauri.conf.json 中覆盖此值：

{
  "bundle": {
    "android": {
      "versionCode": 42
    }
  }
}

最低 SDK 版本

默认最低版本为 Android 7.0（SDK 24）。如需更高要求：

{
  "bundle": {
    "android": {
      "minSdkVersion": 28
    }
  }
}

常见 SDK 版本：

• SDK 24：Android 7.0（Nougat）
• SDK 26：Android 8.0（Oreo）
• SDK 28：Android 9.0（Pie）
• SDK 29：Android 10
• SDK 30：Android 11
• SDK 31：Android 12
• SDK 33：Android 13
• SDK 34：Android 14

构建分发包

Android App Bundle（AAB）— 推荐

Google Play 要求新应用使用 AAB 格式。生成 AAB：

# npm
npm run tauri android build -- --aab

# yarn
yarn tauri android build --aab

# pnpm
pnpm tauri android build -- --aab

# cargo
cargo tauri android build --aab

输出位置：

gen/android/app/build/outputs/bundle/universalRelease/app-universal-release.aab

生成 APK

用于测试或通过其他渠道分发：

# npm
npm run tauri android build -- --apk

# yarn
yarn tauri android build --apk

# pnpm
pnpm tauri android build -- --apk

# cargo
cargo tauri android build --apk

特定架构的构建

针对特定 CPU 架构进行构建：

# Single architecture
npm run tauri android build -- --target aarch64

# Multiple architectures
npm run tauri android build -- --target aarch64 --target armv7

可用目标：

• aarch64 - ARM 64 位（大多数现代设备）
• armv7 - ARM 32 位（较旧设备）
• i686 - Intel 32 位（模拟器）
• x86_64 - Intel 64 位（模拟器、部分 Chromebook）

按架构拆分 APK

为每种架构创建单独的 APK（适用于测试）：

npm run tauri android build -- --apk --split-per-abi

注意：提交到 Play Store 时不需要这样做。Google Play 会从 AAB 自动提供适用于相应架构的版本。

代码签名

生成 Keystore

创建用于签名的发布 keystore：

keytool -genkey -v -keystore release-key.keystore \
  -alias my-app-alias \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000

重要：请妥善保管 keystore。丢失后将无法更新应用。

在 Gradle 中配置签名

创建或更新 gen/android/keystore.properties：

storePassword=your_store_password
keyPassword=your_key_password
keyAlias=my-app-alias
storeFile=/path/to/release-key.keystore

更新 gen/android/app/build.gradle.kts 以使用 keystore：

import java.util.Properties
import java.io.FileInputStream

val keystorePropertiesFile = rootProject.file("keystore.properties")
val keystoreProperties = Properties()
if (keystorePropertiesFile.exists()) {
    keystoreProperties.load(FileInputStream(keystorePropertiesFile))
}

android {
    signingConfigs {
        create("release") {
            keyAlias = keystoreProperties["keyAlias"] as String
            keyPassword = keystoreProperties["keyPassword"] as String
            storeFile = file(keystoreProperties["storeFile"] as String)
            storePassword = keystoreProperties["storePassword"] as String
        }
    }
    buildTypes {
        release {
            signingConfig = signingConfigs.getByName("release")
        }
    }
}

CI/CD 环境变量

对于自动化构建，请使用环境变量：

android {
    signingConfigs {
        create("release") {
            keyAlias = System.getenv("ANDROID_KEY_ALIAS")
            keyPassword = System.getenv("ANDROID_KEY_PASSWORD")
            storeFile = file(System.getenv("ANDROID_KEYSTORE_PATH"))
            storePassword = System.getenv("ANDROID_STORE_PASSWORD")
        }
    }
}

提交到 Google Play 商店

提交前检查清单

1. 应用已使用发布 keystore 签名
2. 版本代码已从上一个版本递增
3. 应用图标已配置所有必需尺寸
4. 截图已准备好（Play Store 要求）
5. 隐私政策URL 已准备好（大多数应用都需要）
6. 内容分级问卷已完成

上传流程

1. 前往 Play Console：https://play.google.com/console/developers
2. 创建应用或选择现有应用
3. 上传 AAB 文件，文件位于：

   gen/android/app/build/outputs/bundle/universalRelease/app-universal-release.aab
   

4. 完成商店详情（标题、描述、截图）
5. 设置内容分级
6. 配置定价和分发
7. 提交审核

首次发布要求

首次提交需要通过 Play Console 手动上传，以验证签名。Google 会通过 Play App Signing 管理应用签名密钥。

自动化说明

Tauri 目前不提供用于创建 Android 版本的内置自动化功能。不过，你可以使用 Google Play Developer API，在 CI/CD 流水线中自动提交。

故障排除

构建因签名错误而失败

确保密钥库路径是绝对路径，或相对于正确的目录：

# Absolute path
storeFile=/Users/username/keys/release-key.keystore

# Relative to gen/android directory
storeFile=../../release-key.keystore

版本代码未递增

如果使用自动计算，请确保已更新 package.json 或 Cargo.toml 中的版本。手动控制时：

{
  "bundle": {
    "android": {
      "versionCode": 2
    }
  }
}

APK 无法安装到设备上

检查最低 SDK 版本兼容性：

# Check device Android version
adb shell getprop ro.build.version.sdk

AAB 过大

可以在测试时使用 --split-per-abi，但对于 Play Store，Google 会自动处理。如果仍然过大：

1. 优化前端资源
2. 使用动态功能模块
3. 启用 ProGuard/R8 混淆

快速参考

常用构建命令

# Development build
npm run tauri android dev

# Release AAB for Play Store
npm run tauri android build -- --aab

# Release APK for testing
npm run tauri android build -- --apk

# Specific architecture
npm run tauri android build -- --aab --target aarch64

文件位置

文件	位置
AAB 输出	gen/android/app/build/outputs/bundle/universalRelease/app-universal-release.aab
APK 输出	gen/android/app/build/outputs/apk/universal/release/app-universal-release-unsigned.apk
Gradle 配置	gen/android/app/build.gradle.kts
密钥库属性	gen/android/keystore.properties
Android 清单	gen/android/app/src/main/AndroidManifest.xml

资源

• Google Play 管理中心
• Tauri Android 文档
• Google Play 发布检查清单
• Play 应用签名