doc: update docs/tauri.md (#996)

2025-08-22 22:16:14 +08:00 · 2025-08-12 10:20:07 +08:00
parent cca2f658b3
commit 2e985e4fee
1 changed files with 250 additions and 19 deletions
--- a/docs/tauri.md
+++ b/docs/tauri.md
@@ -1,7 +1,7 @@
 tauri 备忘清单
 ===

-这个 [tauri](https://tauri.app/) 快速参考备忘单显示了它的常用命令使用清单
+[tauri](https://tauri.app/) 是一个轻量、高性能的跨平台应用开发框架，这里展示了它的常用配置与命令清单

 入门
 ---
@@ -44,7 +44,6 @@ $ bunx create-tauri-app
 [rust](https://www.rust-lang.org/tools/install)| rust安装
 [nodejs](https://nodejs.org/en)| nodejs安装
 [Windows Build Tools](https://visualstudio.microsoft.com/zh-hans/visual-cpp-build-tools/)| Microsoft C++ 生成工具 (for windows)
-[Android Studio](https://developer.android.google.cn/studio?hl=zh-cn)|安卓开发工具

 ### 启动 Tauri 开发窗口

@@ -112,7 +111,7 @@ RUST_BACKTRACE=1 tauri dev
 Window 上这样开启

 ```bash
-set RUST_BACKTRACE=1 
+set RUST_BACKTRACE=1
 tauri dev
 ```

@@ -153,46 +152,278 @@ tauri = { version = "...", features = ["...", "devtools"] }

 在文件 `src-tauri/Cargo.toml` 中启用 `devtools Cargo` 功能

+移动端开发
+---
+
+### 注意事项
+<!--rehype:wrap-class=col-span-2-->
+
+Tauri 使用系统原生的 `Webview`，而不像 Electron 那样将完整的 `Chromium` 打包进应用，因此构建产物体积相当小。
+
+但各手机厂商对于 `Webview` 的支持程度不同，因此在部分设备可能会出现一些兼容性问题。
+
 安卓开发
 ---

+### 安装 Android Studio
+<!--rehype:wrap-class=row-span-2-->
+
+在进行安卓开发之前，需要首先安装 [Android Studio](https://developer.android.google.cn/studio?hl=zh-cn) 并配置好环境变量。
+
+安装后，打开 `Settings`，切换到 `Languages & Frameworks` > `Android SDK` 界面。
+> 可以在这个页面更改 `Android SDK Location` 以调整 SDK 安装目录
+
+安装以下内容：
+
+- Android SDK Platform
+- Android SDK Platform-Tools
+- NDK (Side by side)
+- Android SDK Build-Tools
+- Android SDK Command-line Tools
+
 ### 环境变量
 <!--rehype:wrap-class=col-span-2-->
-`JAVA_HOME`

-`ANDROID_HOME`
+- `JAVA_HOME`: 若无其他 JDK 环境，可以配置为 Android Studio 安装目录下的 jbr 目录。

-`NDK_HOME`
+- `ANDROID_HOME`: 配置为 Android SDK Location 目录下的 sdk 目录。

-### 准备目标
+- `NDK_HOME`: 配置为 Android SDK Location 目录下的 ndk 下的 ndk 版本号目录。
+
+### 编译目标
 <!--rehype:wrap-class=col-span-2-->

+Rust 默认只安装当前主机平台的编译目标（比如在 macOS 上默认就是 `x86_64-apple-darwin`）。
+如果你想编译到其它平台或架构，就需要使用 `rustup target add` 安装对应的编译目标。
+
+Android 应用打包时，一般会把编译的这几种架构的库文件全都放进 APK/ABB 中，系统会自动选择匹配的那个。
+
+| target                      | CPU 架构         | 常见设备/场景             |
+| --------------------------- | -------------- | ------------------- |
+| **aarch64-linux-android**   | ARM 64 位       | 新款安卓手机（主流）          |
+| **armv7-linux-androideabi** | ARM 32 位       | 老款安卓手机（较少见）         |
+| **i686-linux-android**      | Intel x86 32 位 | 早期安卓模拟器（老旧）         |
+| **x86_64-linux-android**   | Intel x86 64 位 | 安卓模拟器、新款 Chromebook |
+
 ```bash
-$ npm install @tauri-apps/cli@next @tauri-apps/api@next
-$ npm run tauri migrate
 $ rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android
-$ rm -r src-tauri/gen
-$ npm run tauri android init
-$ npm run tauri icon
 ```

-修改应用名：%app_path%\src-tauri\gen\android\app\src\main\res\values\strings.xml
+### 创建 Android 项目
+<!--rehype:wrap-class=row-span-3-->
+
+创建基础 Tauri 项目：

-### 编译
-<!--rehype:wrap-class=col-span-2-->
 ```bash
-$ npm run tauri android dev
-$ npm run tauri android build
+# 创建 tauri 项目
+$ npm create tauri-app@latest
+# 安装依赖
+$ npm install
 ```

-### 签名
+手动创建：
+
+```bash
+$ npm install -D @tauri-apps/cli@latest
+# 进入项目目录初始化，按照提示输入即可
+$ npx tauri init
+```
+
+创建后，则可以执行以下命令：
+
+```bash
+# 初始化 Android 开发配置
+$ npx tauri android init
+# 开发 Android 应用
+$ npx tauri android dev
+# 构建 Android 应用
+$ npx tauri android build
+```
+
+### 开发调试
 <!--rehype:wrap-class=col-span-2-->
+
+首先需要在开发环境下打开应用，才能进行调试。
+
+在浏览器打开检查页面，根据浏览器不同，地址也不同，edge 浏览器是 `edge://inspect`，chrome 浏览器是 `chrome://inspect`。
+
+在检查页面中，会显示当前运行的应用，点击 `inspect` 即可打开调试工具。
+
+### 生成签名
+<!--rehype:wrap-class=col-span-2-->
+
+Android 系统要求所有 APK 必须先使用证书进行数字签名，然后才能安装到设备上或进行更新。
+
+`keytool` 是 Java 数据证书管理工具。
+
+可以在 `JAVA_HOME` 环境变量指向的目录下的 `/bin/` 目录中找到 `keytool.exe`。
+
+执行以下命令之后按照提示进行输入即可。
+
+```bash
+$ keytool -genkey -v -keystore 自定义的数据文件名称 -storetype JKS -keyalg RSA -keysize 2048 -validity 10000 -alias 自定义的证书别名
+```
+
+如果是要上架应用商店的，要如实填写。否则可能会导致因信息不对从而上架失败。
+
+输入完毕，确认后，工具会要求设置密码。记住密码，后面会用到。
+
+完成以上操作后，在当前工作目录下会生成一个 `自定义的数据文件名称.keystore` 文件。
+
+### 手动签名
+<!--rehype:wrap-class=col-span-2-->
+
 ```bash
 $ keytool -genkey -alias android.keystore -keyalg RSA -validity 20000 -keystore android.keystore
 $ zipalign -p -f -v 4 unsigned.apk release.apk
 $ apksigner sign --ks android.keystore release.apk
 ```

+### 自动签名
+<!--rehype:wrap-class=col-span-2-->
+
+创建 `src-tauri/gen/android/keystore.properties` 文件。
+
+```properties
+storePassword=数据文件密码
+keyPassword=证书密码
+keyAlias=自定义的证书别名
+storeFile=自定义的数据文件名称.keystore
+```
+
+需要注意，在 windows 下，`storeFile` 需要 `C:\\Program Files\\Android` 这样的格式。
+
+随后找到 `src-tauri/gen/android/app/build.gradle.kts` 文件，添加以下内容：
+
+```kotlin
+import java.io.FileInputStream
+
+// ...
+android {
+  defaultConfig {
+    // ...
+  }
+  signingConfigs {
+    create("release") {
+        val keystorePropertiesFile = rootProject.file("keystore.properties")
+        val keystoreProperties = Properties()
+        if (keystorePropertiesFile.exists()) {
+            keystoreProperties.load(FileInputStream(keystorePropertiesFile))
+        }
+
+        keyAlias = keystoreProperties["keyAlias"] as String
+        keyPassword = keystoreProperties["keyPassword"] as String
+        storeFile = file(keystoreProperties["storeFile"] as String)
+        storePassword = keystoreProperties["storePassword"] as String
+    }
+  }
+  buildTypes {
+    // ...
+    getByName("release") {
+      signingConfig = signingConfigs.getByName("release")
+      // ...
+    }
+  }
+}
+```
+
+配置完毕后，当执行 `npm run tauri android build` 时，会自动对构建的 APK/AAB 文件进行签名。
+
+iOS 开发
+---
+
+### 预先准备
+
+根据苹果政策，MacOS 不允许运行在非 Mac 硬件上，而开发所依赖的 Xcode 工具链只在 MacOS 上可用。
+
+因此，为了进行开发 iOS 和 MacOS 应用，必须要有一台 Mac 设备。
+
+对应用进行签名和发布，需要加入 [Apple Developer Program（年费 99 美元）](https://developer.apple.com/programs/whats-included/)。
+
+不付费可以正常使用 Xcode 等工具，但无法进行正式签名和在 App Store 上架。
+
+&nbsp;
+
+### 签名
+
+iOS 应用的签名现在已经非常简单了。
+
+在 Xcode 打开项目，登录 Apple Developer 账号，在项目配置中找到并勾选自动管理签名即可。
+
+Xcode 会自动帮助我们管理证书，签名等。
+
+&nbsp;
+
+### 开发调试
+
+首先需要在开发环境下打开应用，才能进行调试。
+
+在 Mac 上打开 Safari 浏览器，开启开发者模式，接着找到需要调试的设备即可。
+
+如果是真机调试，则需要在设备上开启开发者模式。
+
+&nbsp;
+
+### 环境搭建
+<!--rehype:wrap-class=col-span-2-->
+
+#### 安装 Xcode
+
+Xcode 是苹果官方的开发工具，提供了完整的开发环境，包括测试，分发，模拟器等。
+
+需要注意的是，Xcode 的版本并非越新越好，而是要根据当前设备的 MacOS 的系统版本来选择。
+
+前往 [Xcode 页面](https://developer.apple.com/cn/xcode/) 下载安装 Xcode。
+
+#### 安装 [Homebrew](https://brew.sh/zh-cn/)
+
+```bash
+$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+#### 使用 Homebrew 安装 [Cocoapods](https://cocoapods.org/)
+
+```bash
+brew install cocoapods
+```
+
+#### 增加编译目标
+
+```bash
+$ rustup target add aarch64-apple-ios x86_64-apple-ios aarch64-apple-ios-sim
+```
+
+### 创建 iOS 项目
+<!--rehype:wrap-class=col-span-1-->
+
+首先创建基础 Tauri 项目。
+
+```bash
+# 创建 tauri 项目
+$ npm create tauri-app@latest
+# 安装依赖
+$ npm install
+```
+
+手动创建：
+
+```bash
+$ npm install -D @tauri-apps/cli@latest
+# 进入项目目录初始化，按照提示输入即可
+$ npx tauri init
+```
+
+创建后，则可以执行以下命令：
+
+```bash
+# 初始化 iOS 开发配置
+$ npx tauri ios init
+# 开发 iOS 应用
+$ npx tauri ios dev
+# 构建 iOS 应用
+$ npx tauri ios build
+```
+
 配置
 ---

@@ -294,7 +525,7 @@ $ apksigner sign --ks android.keystore release.apk
 #### 隔离模式。建议出于安全目的

 ```json
-{ 
+{
  "use": "isolation",
  "options": { "dir": string }
 }