tauri-packaging

Tauri 打包与分发技能,指导桌面端（Windows/macOS/Linux）与移动端（Android/iOS）的构建、签名和分发。触发场景: - 需要构建生产安装包（exe/dmg/deb/apk/aab/ipa） - 需要配置各平台打包参数 - 需要代码签名（Windows 证书 / Android keystore / iOS 描述文件） - 需要减小安装包体积 - 需要设置应用图标和元数据 - 需要打包 Android / iOS App 触发词: 打包、构建、build、发布、安装包、exe、dmg、deb、apk、aab、ipa、签名、分发、release、android build、ios build、移动端打包

跳到安装

仓库: bkywksj/knowledge-base
最近来源活动: 2026年5月16日 03:53
检测到的 SKILL.md 语言: 中文
星标: 313
分支: 60

安装方式

默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

直接命令不会经过审查 Prompt；运行前请先检查来源。

npx skills add https://github.com/bkywksj/knowledge-base --skill tauri-packaging

命令会保持在同一行。复制前请横向滚动并检查完整内容。

想先保存到本地？可下载 SkillsMP 当前能够提供的文件。

检查来源文件

决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。

SKILL.md

来源说明 · 只读预览

返回搜索返回安装

SKILL.md

来源说明 · 只读预览

name

tauri-packaging

description

Tauri 打包与分发

本项目同时支持桌面端 + 移动端：桌面三平台靠 pnpm tauri build，Android 靠 pnpm tauri android build，iOS 靠 pnpm tauri ios build（需 macOS）。移动端踩坑较多，单独看下方「移动端打包」章节。

桌面端构建命令

# 构建所有平台安装包
pnpm tauri build

# 仅构建特定格式
pnpm tauri build --bundles msi    # Windows MSI
pnpm tauri build --bundles nsis   # Windows NSIS
pnpm tauri build --bundles dmg    # macOS DMG
pnpm tauri build --bundles deb    # Linux DEB
pnpm tauri build --bundles appimage # Linux AppImage

# Debug 构建(包含 DevTools)
pnpm tauri build --debug

打包配置 (tauri.conf.json)

基础配置

{
  "productName": "MyApp",
  "version": "1.0.0",
  "identifier": "com.company.myapp",
  "bundle": {
    "active": true,
    "targets": "all",
    "icon": [
      "icons/32x32.png",
      "icons/128x128.png",
      "icons/128x128@2x.png",
      "icons/icon.icns",
      "icons/icon.ico"
    ],
    "resources": [],
    "copyright": "Copyright (c) 2026 Company",
    "category": "Productivity",
    "shortDescription": "我的桌面应用",
    "longDescription": "一个使用 Tauri 构建的跨平台桌面应用"
  }
}

Windows 配置

{
  "bundle": {
    "windows": {
      "certificateThumbprint": null,
      "digestAlgorithm": "sha256",
      "timestampUrl": "",
      "wix": null,
      "nsis": {
        "displayLanguageSelector": true,
        "languages": ["SimpChinese", "English"],
        "installerIcon": "icons/icon.ico"
      }
    }
  }
}

macOS 配置

{
  "bundle": {
    "macOS": {
      "entitlements": null,
      "frameworks": [],
      "minimumSystemVersion": "10.15",
      "signingIdentity": null
    }
  }
}

Linux 配置

{
  "bundle": {
    "linux": {
      "deb": {
        "depends": ["libwebkit2gtk-4.0-37"],
        "section": "utility"
      },
      "appimage": {
        "bundleMediaFramework": false
      }
    }
  }
}

图标生成

# 从 1024x1024 PNG 生成所有平台图标
pnpm tauri icon path/to/icon-1024x1024.png

需要准备的图标:

文件	尺寸	平台
`icon.ico`	多尺寸合一	Windows
`icon.icns`	多尺寸合一	macOS
`32x32.png`	32x32	通用
`128x128.png`	128x128	通用
`128x128@2x.png`	256x256	HiDPI

体积优化

# src-tauri/Cargo.toml
[profile.release]
opt-level = "z"       # 最小体积
lto = true            # 链接时优化
codegen-units = 1     # 单代码生成单元
strip = true          # 剥离调试信息
panic = "abort"       # abort 而非 unwind

典型打包体积

平台	基础模板	中等应用
Windows (.msi)	~3 MB	~5-10 MB
macOS (.dmg)	~5 MB	~8-15 MB
Linux (.deb)	~4 MB	~6-12 MB

桌面端输出位置

src-tauri/target/release/bundle/
├── msi/        → .msi 安装包 (Windows)
├── nsis/       → .exe 安装程序 (Windows)
├── dmg/        → .dmg 磁盘映像 (macOS)
├── macos/      → .app 应用包 (macOS)
├── deb/        → .deb 包 (Debian/Ubuntu)
└── appimage/   → .AppImage (通用 Linux)

便携版（Portable Zip）打包

本项目支持便携模式：exe 同级有 portable.txt 哨兵文件就把数据写到安装目录而不是 C 盘 AppData。 resolver 在 src-tauri/src/services/data_dir.rs::DataDirResolver::resolve() 实现，优先级：env > portable > pointer > default。

便携模式触发条件

哨兵文件状态	数据根目录
`<exe同级>/portable.txt` 不存在	走默认（C 盘 AppData）或指针文件
`<exe同级>/portable.txt` 存在 + 内容空	`<exe同级>/data/`
`<exe同级>/portable.txt` 存在 + 绝对路径内容	该绝对路径
`<exe同级>/portable.txt` 存在 + 相对路径内容	`<exe同级>/<相对路径>/`

打 portable.zip 的方法

不需要改 tauri.conf.json / NSIS 配置。只要：

用正常的 pnpm tauri build 或 CI 出官方 NSIS 安装包
用 7-Zip 解压 NSIS exe（NSIS 内部本质是 7z）拿到程序文件目录
加一个空的 portable.txt
zip 打包

详细步骤见 release-publish 技能的「便携版（Portable Zip）」章节。

不做的事

❌ 不改 NSIS installMode 为 currentUser：会破坏老用户升级路径
❌ 不在 installer-hooks.nsi 里自动写 portable.txt：增加分支复杂度，老用户升级风险
❌ 不给 portable.zip 接 updater：便携版升级靠用户重新下载解压覆盖

🤖 移动端打包（Android）

dev 模式 vs build 模式（先搞清楚这个）

模式	命令	webview 加载来源	是否依赖电脑	用途
dev	`pnpm tauri android dev`	`http://<电脑IP>:1421`（vite live server）	✅ 必须连电脑（同 Wi-Fi 或 adb reverse），hot reload	日常开发
build	`pnpm tauri android build`	`tauri://localhost`（APK 内打包好的静态资源）	❌ 完全独立，断 USB / 关电脑都能用	测试 / 发布

关键：发布版（build 模式）APK 把 frontendDist（dist/）和 libknowledge_base_lib.so 都打进 APK，invoke 走 webview↔JNI 桥，不走任何网络。dev 模式那个 http://192.168.x.x:1421 连不上的错误只在 dev 模式有。

构建命令

# debug APK（含 debuginfo，体积大 ~300MB+，可直接 adb install）
pnpm tauri android build --debug --apk
# release APK（LTO + strip，体积小 ~50-100MB，需签名才能上架）
pnpm tauri android build --apk
# AAB（Google Play 上架格式）
pnpm tauri android build --aab
# 只构建某个 ABI（加快编译，去掉 universal 多 ABI）
pnpm tauri android build --debug --apk --target aarch64

🔴 项目路径含中文 → 必须设 CARGO_TARGET_DIR

本项目路径 E:\my\桌面软件tauri\knowledge_base 含中文，Android NDK 的 ld.lld 在 Windows 下用 ANSI codepage 解析路径，遇到中文会报：

ld.lld: error: cannot open ...knowledge_base_lib.*.rcgu.o : unspecified system_category error

所有 tauri android 命令必须带 CARGO_TARGET_DIR 指到纯 ASCII 路径（用 inline env VAR=val，不要 export，否则 background wrapper 会吞掉）：

mkdir -p /c/cargo-target/kb-android
env CARGO_TARGET_DIR="C:\\cargo-target\\kb-android" pnpm tauri android build --debug --apk

subst K: / mklink /J 都不行 —— tauri-cli 的 mobile 模块会 canonicalize 还原虚拟盘符，触发 AssetDirOutsideOfAppRoot。只能改 cargo 编译输出目录。详见 bug-detective 技能。

APK / AAB 输出位置

src-tauri/gen/android/app/build/outputs/
├── apk/
│   ├── universal/debug/app-universal-debug.apk   ← 4 ABI 合一（体积最大）
│   ├── arm64/debug/app-arm64-debug.apk           ← 只 arm64（现代手机用这个）
│   ├── universal/release/app-universal-release.apk
│   └── ...
└── bundle/
    └── universalRelease/app-universal-release.aab ← 传 Google Play

装机：adb install -r src-tauri/gen/android/app/build/outputs/apk/universal/debug/app-universal-debug.apk

Android 签名 — 本项目已配好（T-M019 一期）

debug APK 用 Android SDK 自带的 debug keystore 自动签名（同一台机器固定，但 CI runner 的 debug keystore 跟本地不一样，debug→debug 跨机器更新会签名不匹配）。release 用本项目自己的 keystore：

keystore：src-tauri/gen/android/kb-release.jks（alias kb，RSA 2048，有效期到 2053；已 .gitignore，密码见 key.properties / 维护者密码管理器 / memory project_android_keystore.md）
配置：src-tauri/gen/android/key.properties（也 .gitignore）→ app/build.gradle.kts 的 signingConfigs.release 读它：
- key.properties 存在 → pnpm tauri android build --apk/--aab 自动用 kb-release.jks 签名
- 不存在（如别人 fresh clone）→ release 不签名（仅 assembleRelease 不报错），debug 不受影响
CI 上：.jks（base64）+ storePassword/keyPassword/keyAlias 已放 GitHub Secrets（主仓 + 备用仓都配了），android.yml 的 release 路径解码还原 kb-release.jks + key.properties 后再 tauri android build --apk --aab（已接好）

# 验签：看 release 变体用的是不是 kb-release.jks
cd src-tauri/gen/android && ./gradlew :app:signingReport | grep -A4 Release

🔴 更新签名一致性铁律：第一个分发给用户的 release APK 用了 kb-release.jks → 此后所有版本必须用同一个 keystore，否则用户"检查更新→下载新 APK"会因签名不匹配装不上（INSTALL_FAILED_UPDATE_INCOMPATIBLE，只能卸载重装丢数据）。keystore 丢了 = 永远无法给已安装用户推更新。.jks + 两个密码务必备份（云盘 + 密码管理器）。

现在手机上装的是「本地 debug APK」，将来换成 release APK 时，老用户需先卸载再装（debug↔release 签名不同）；之后 release→release 才一致。

AndroidManifest 权限（与 capabilities 是两套）

src-tauri/gen/android/app/src/main/AndroidManifest.xml 里的 <uses-permission> 是 Android 系统层权限，跟 src-tauri/capabilities/*.json 的 Tauri 权限是两回事，两边都要声明：

功能	AndroidManifest `<uses-permission>`	备注
联网（dev server / WebDAV / AI API）	`android.permission.INTERNET`	tauri 默认已有
扫码（WebView getUserMedia 调摄像头）	`android.permission.CAMERA`	不声明则 `onPermissionRequest` 里申请运行时权限被系统直接拒，弹 `NotAllowedError`
语音录入（getUserMedia 录音）	`android.permission.RECORD_AUDIO` + `MODIFY_AUDIO_SETTINGS`	同上

⚠️ pnpm tauri android init 会覆盖 gen/android/ 下大部分文件，手改的 AndroidManifest / strings.xml / 图标会丢，改完要么不再 init，要么记下手改内容重新打。

图标 / 应用名同步（不会自动跟 PC 同步）

PC 端图标源：src-tauri/icons/（icon.png 512×512 + tauri icon 生成的全套）
Android 用：src-tauri/gen/android/app/src/main/res/mipmap-*/ —— tauri android init 时从 src-tauri/icons/android/ 拷一份，之后不会自动跟 PC 同步
改图标：把整个 src-tauri/icons/android/（含 mipmap-* 和 values/ic_launcher_background.xml，别漏 values 子目录否则 Gradle 报 resource color/ic_launcher_background not found）拷到 gen/android/.../res/
应用名：src-tauri/gen/android/app/src/main/res/values/strings.xml 的 app_name / main_activity_title（默认是 productName，本项目手改为「知识库」）

软键盘 / viewport

AndroidManifest.xml activity 需 android:windowSoftInputMode="adjustResize"，否则配合 enableEdgeToEdge() 时 input 获得焦点也不弹键盘
index.html viewport 建议 width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover

🍎 移动端打包（iOS，需 macOS）

pnpm tauri ios init        # 一次性，生成 src-tauri/gen/apple/
pnpm tauri ios dev         # 模拟器 / 真机 dev
pnpm tauri ios build       # 生成 .ipa（需 Apple Developer Program 账号 + 描述文件）

签名走 Xcode 的 Signing & Capabilities（Team + Provisioning Profile），不像 Android 用 keystore
上架走 TestFlight / App Store Connect
本项目 iOS 链路尚未跑通（无 Mac 设备），相关任务见 docs/tasks/mobile-migration-tasks.md T-M005/T-M016/T-M018

版本管理（桌面 / 移动端两条独立版本线）

版本线	改哪里	tag	CI workflow	更新源
桌面（1.x）	三处同步：`package.json` / `src-tauri/Cargo.toml` / `src-tauri/tauri.conf.json` 的 version	`v..*`（例 `v1.9.0`）	`release.yml`	`update.json`
移动端（Android）（从 0.1.0 起）	只改一处：`src-tauri/tauri.android.conf.json` 的 `"version"`	`mobile-v..*`（例 `mobile-v0.1.0`）	`android.yml`	`update-mobile.json`

Tauri 2 构建 Android 时自动把 tauri.android.conf.json 合并覆盖到 tauri.conf.json，所以 Android APK 的 versionName 和编译进去的 package_info().version 都用这个独立的移动版本号，跟桌面 1.x 解耦。 不要把移动版本号往回调（Tauri 从它推 Android versionCode，倒退会让用户装不上）。

# 桌面（三处）
package.json:           "version": "1.0.0"
src-tauri/Cargo.toml:   version = "1.0.0"
src-tauri/tauri.conf.json: "version": "1.0.0"
# 移动端（一处）
src-tauri/tauri.android.conf.json: "version": "0.1.0"

CI 自动构建（推荐）

桌面三平台：.github/workflows/release.yml，推送 v*.*.* Tag 后自动构建 Windows/macOS/Linux 安装包。用 /release 命令一键发布，详见 release-publish 技能。
Android：.github/workflows/android.yml —— 触发方式：workflow_dispatch（手动，可选 debug / release）或推 mobile-v*.*.* tag（普通 push 到 master 不触发；前缀 mobile- 与桌面 v*.*.* 区分，互不打架）：
- debug：SDK debug keystore 自签名 → APK（侧载，仅 workflow_dispatch 选 debug 时）
- release（tag 触发 / workflow_dispatch 选 release）：从 Secrets 还原 kb-release.jks + key.properties → tauri android build --apk --aab 正式签名 → 产物起稳定名 Knowledge.Base_<移动版本>_android-arm64.apk（+ .aab，移动版本读 tauri.android.conf.json）→ tag 触发时附到本仓库 GitHub Release 草稿（tag = mobile-v<移动版本>）；同时设 TAURI_SIGNING_PRIVATE_KEY
- ⚠️ 被 tag 的那个 commit 消息不能含 [skip ci]，否则 tag push 也会被跳过
- 6 个 Secrets（ANDROID_KEYSTORE_BASE64 / ANDROID_KEYSTORE_PASSWORD / ANDROID_KEY_ALIAS / ANDROID_KEY_PASSWORD / TAURI_SIGNING_PRIVATE_KEY / TAURI_SIGNING_PRIVATE_KEY_PASSWORD）在主 bkywksj/knowledge-base + 备用 allebamala/knowledge-base 两个仓库都已配
- App 内"检查更新"闭环：release-publish 技能「移动端（Android）独立发布」流程把 release APK 放进 releases/mobile-v<版本>/ + 生成 update-mobile.json（指向 release 仓 raw / R2 上的 APK），App 的 check_mobile_update（src-tauri/src/commands/mobile_update.rs）读它拿直链。
iOS：CI 尚未接（需 Apple Developer 账号 + macOS runner，T-M020 待办）。

常见错误

错误做法	正确做法
不配置 release profile	添加 LTO + strip 优化体积
图标尺寸不全	使用 `tauri icon` 命令自动生成
版本号不同步	3 处版本号保持一致
不测试安装包	每次发布前在干净环境安装测试
不设置应用标识	identifier 使用反向域名格式
Rust 中启动子进程未设 `CREATE_NO_WINDOW`	打包后变 GUI 进程，所有 `Command::new()` 必须设 `creation_flags(0x08000000)`
`productName` 含中文导致 WiX MSI 打包失败	改用 NSIS (`"targets": ["nsis"]`) 或改 productName 为纯 ASCII
`bundle.targets` 设为 `"all"` 在 CI 上出错	CI 中通过 `--bundles` 参数指定，本地可用 `["nsis"]`
Android：项目路径含中文直接 `tauri android build`	必须 `env CARGO_TARGET_DIR="C:\\cargo-target\\<name>-android"` 前缀（NDK ld.lld 不认非 ASCII 路径）
以为发布 APK 还要连电脑	`tauri android build` 出的 APK 是独立的（`tauri://localhost` 读 APK 内资源），只有 `tauri android dev` 模式才连 dev server
手改 `gen/android/` 后又跑 `tauri android init`	init 会覆盖 AndroidManifest / strings.xml / 图标，手改的全丢；改完别再 init，或记下手改内容重新打
Android 权限只在 capabilities 里声明	AndroidManifest `<uses-permission>` 和 Tauri capabilities 是两套，摄像头/录音/联网两边都要声明
*同步 Android 图标只拷 `mipmap-`**	必须连 `values/ic_launcher_background.xml` 一起拷，否则 Gradle 报 `resource color/ic_launcher_background not found`
release APK 用 debug keystore	上架前必须用自己的 keystore（`key.properties` + `signingConfigs`），debug 签名不能上架且 keystore 丢了无法更新已上架应用
input 获焦不弹键盘（Android）	activity 加 `android:windowSoftInputMode="adjustResize"`

name

tauri-packaging

description

Tauri 打包与分发

本项目同时支持桌面端 + 移动端：桌面三平台靠 pnpm tauri build，Android 靠 pnpm tauri android build，iOS 靠 pnpm tauri ios build（需 macOS）。移动端踩坑较多，单独看下方「移动端打包」章节。

桌面端构建命令

# 构建所有平台安装包
pnpm tauri build

# 仅构建特定格式
pnpm tauri build --bundles msi    # Windows MSI
pnpm tauri build --bundles nsis   # Windows NSIS
pnpm tauri build --bundles dmg    # macOS DMG
pnpm tauri build --bundles deb    # Linux DEB
pnpm tauri build --bundles appimage # Linux AppImage

# Debug 构建(包含 DevTools)
pnpm tauri build --debug

打包配置 (tauri.conf.json)

基础配置

{
  "productName": "MyApp",
  "version": "1.0.0",
  "identifier": "com.company.myapp",
  "bundle": {
    "active": true,
    "targets": "all",
    "icon": [
      "icons/32x32.png",
      "icons/128x128.png",
      "icons/128x128@2x.png",
      "icons/icon.icns",
      "icons/icon.ico"
    ],
    "resources": [],
    "copyright": "Copyright (c) 2026 Company",
    "category": "Productivity",
    "shortDescription": "我的桌面应用",
    "longDescription": "一个使用 Tauri 构建的跨平台桌面应用"
  }
}

Windows 配置

{
  "bundle": {
    "windows": {
      "certificateThumbprint": null,
      "digestAlgorithm": "sha256",
      "timestampUrl": "",
      "wix": null,
      "nsis": {
        "displayLanguageSelector": true,
        "languages": ["SimpChinese", "English"],
        "installerIcon": "icons/icon.ico"
      }
    }
  }
}

macOS 配置

{
  "bundle": {
    "macOS": {
      "entitlements": null,
      "frameworks": [],
      "minimumSystemVersion": "10.15",
      "signingIdentity": null
    }
  }
}

Linux 配置

{
  "bundle": {
    "linux": {
      "deb": {
        "depends": ["libwebkit2gtk-4.0-37"],
        "section": "utility"
      },
      "appimage": {
        "bundleMediaFramework": false
      }
    }
  }
}

图标生成

# 从 1024x1024 PNG 生成所有平台图标
pnpm tauri icon path/to/icon-1024x1024.png

需要准备的图标:

文件	尺寸	平台
`icon.ico`	多尺寸合一	Windows
`icon.icns`	多尺寸合一	macOS
`32x32.png`	32x32	通用
`128x128.png`	128x128	通用
`128x128@2x.png`	256x256	HiDPI

体积优化

# src-tauri/Cargo.toml
[profile.release]
opt-level = "z"       # 最小体积
lto = true            # 链接时优化
codegen-units = 1     # 单代码生成单元
strip = true          # 剥离调试信息
panic = "abort"       # abort 而非 unwind

典型打包体积

平台	基础模板	中等应用
Windows (.msi)	~3 MB	~5-10 MB
macOS (.dmg)	~5 MB	~8-15 MB
Linux (.deb)	~4 MB	~6-12 MB

桌面端输出位置

src-tauri/target/release/bundle/
├── msi/        → .msi 安装包 (Windows)
├── nsis/       → .exe 安装程序 (Windows)
├── dmg/        → .dmg 磁盘映像 (macOS)
├── macos/      → .app 应用包 (macOS)
├── deb/        → .deb 包 (Debian/Ubuntu)
└── appimage/   → .AppImage (通用 Linux)

便携版（Portable Zip）打包

本项目支持便携模式：exe 同级有 portable.txt 哨兵文件就把数据写到安装目录而不是 C 盘 AppData。 resolver 在 src-tauri/src/services/data_dir.rs::DataDirResolver::resolve() 实现，优先级：env > portable > pointer > default。

便携模式触发条件

哨兵文件状态	数据根目录
`<exe同级>/portable.txt` 不存在	走默认（C 盘 AppData）或指针文件
`<exe同级>/portable.txt` 存在 + 内容空	`<exe同级>/data/`
`<exe同级>/portable.txt` 存在 + 绝对路径内容	该绝对路径
`<exe同级>/portable.txt` 存在 + 相对路径内容	`<exe同级>/<相对路径>/`

打 portable.zip 的方法

不需要改 tauri.conf.json / NSIS 配置。只要：

用正常的 pnpm tauri build 或 CI 出官方 NSIS 安装包
用 7-Zip 解压 NSIS exe（NSIS 内部本质是 7z）拿到程序文件目录
加一个空的 portable.txt
zip 打包

详细步骤见 release-publish 技能的「便携版（Portable Zip）」章节。

不做的事

❌ 不改 NSIS installMode 为 currentUser：会破坏老用户升级路径
❌ 不在 installer-hooks.nsi 里自动写 portable.txt：增加分支复杂度，老用户升级风险
❌ 不给 portable.zip 接 updater：便携版升级靠用户重新下载解压覆盖

🤖 移动端打包（Android）

dev 模式 vs build 模式（先搞清楚这个）

模式	命令	webview 加载来源	是否依赖电脑	用途
dev	`pnpm tauri android dev`	`http://<电脑IP>:1421`（vite live server）	✅ 必须连电脑（同 Wi-Fi 或 adb reverse），hot reload	日常开发
build	`pnpm tauri android build`	`tauri://localhost`（APK 内打包好的静态资源）	❌ 完全独立，断 USB / 关电脑都能用	测试 / 发布

关键：发布版（build 模式）APK 把 frontendDist（dist/）和 libknowledge_base_lib.so 都打进 APK，invoke 走 webview↔JNI 桥，不走任何网络。dev 模式那个 http://192.168.x.x:1421 连不上的错误只在 dev 模式有。

构建命令

# debug APK（含 debuginfo，体积大 ~300MB+，可直接 adb install）
pnpm tauri android build --debug --apk
# release APK（LTO + strip，体积小 ~50-100MB，需签名才能上架）
pnpm tauri android build --apk
# AAB（Google Play 上架格式）
pnpm tauri android build --aab
# 只构建某个 ABI（加快编译，去掉 universal 多 ABI）
pnpm tauri android build --debug --apk --target aarch64

🔴 项目路径含中文 → 必须设 CARGO_TARGET_DIR

本项目路径 E:\my\桌面软件tauri\knowledge_base 含中文，Android NDK 的 ld.lld 在 Windows 下用 ANSI codepage 解析路径，遇到中文会报：

ld.lld: error: cannot open ...knowledge_base_lib.*.rcgu.o : unspecified system_category error

所有 tauri android 命令必须带 CARGO_TARGET_DIR 指到纯 ASCII 路径（用 inline env VAR=val，不要 export，否则 background wrapper 会吞掉）：

mkdir -p /c/cargo-target/kb-android
env CARGO_TARGET_DIR="C:\\cargo-target\\kb-android" pnpm tauri android build --debug --apk

subst K: / mklink /J 都不行 —— tauri-cli 的 mobile 模块会 canonicalize 还原虚拟盘符，触发 AssetDirOutsideOfAppRoot。只能改 cargo 编译输出目录。详见 bug-detective 技能。

APK / AAB 输出位置

src-tauri/gen/android/app/build/outputs/
├── apk/
│   ├── universal/debug/app-universal-debug.apk   ← 4 ABI 合一（体积最大）
│   ├── arm64/debug/app-arm64-debug.apk           ← 只 arm64（现代手机用这个）
│   ├── universal/release/app-universal-release.apk
│   └── ...
└── bundle/
    └── universalRelease/app-universal-release.aab ← 传 Google Play

装机：adb install -r src-tauri/gen/android/app/build/outputs/apk/universal/debug/app-universal-debug.apk

Android 签名 — 本项目已配好（T-M019 一期）

keystore：src-tauri/gen/android/kb-release.jks（alias kb，RSA 2048，有效期到 2053；已 .gitignore，密码见 key.properties / 维护者密码管理器 / memory project_android_keystore.md）
配置：src-tauri/gen/android/key.properties（也 .gitignore）→ app/build.gradle.kts 的 signingConfigs.release 读它：
- key.properties 存在 → pnpm tauri android build --apk/--aab 自动用 kb-release.jks 签名
- 不存在（如别人 fresh clone）→ release 不签名（仅 assembleRelease 不报错），debug 不受影响
CI 上：.jks（base64）+ storePassword/keyPassword/keyAlias 已放 GitHub Secrets（主仓 + 备用仓都配了），android.yml 的 release 路径解码还原 kb-release.jks + key.properties 后再 tauri android build --apk --aab（已接好）

# 验签：看 release 变体用的是不是 kb-release.jks
cd src-tauri/gen/android && ./gradlew :app:signingReport | grep -A4 Release

🔴 更新签名一致性铁律：第一个分发给用户的 release APK 用了 kb-release.jks → 此后所有版本必须用同一个 keystore，否则用户"检查更新→下载新 APK"会因签名不匹配装不上（INSTALL_FAILED_UPDATE_INCOMPATIBLE，只能卸载重装丢数据）。keystore 丢了 = 永远无法给已安装用户推更新。.jks + 两个密码务必备份（云盘 + 密码管理器）。

现在手机上装的是「本地 debug APK」，将来换成 release APK 时，老用户需先卸载再装（debug↔release 签名不同）；之后 release→release 才一致。

AndroidManifest 权限（与 capabilities 是两套）

功能	AndroidManifest `<uses-permission>`	备注
联网（dev server / WebDAV / AI API）	`android.permission.INTERNET`	tauri 默认已有
扫码（WebView getUserMedia 调摄像头）	`android.permission.CAMERA`	不声明则 `onPermissionRequest` 里申请运行时权限被系统直接拒，弹 `NotAllowedError`
语音录入（getUserMedia 录音）	`android.permission.RECORD_AUDIO` + `MODIFY_AUDIO_SETTINGS`	同上

⚠️ pnpm tauri android init 会覆盖 gen/android/ 下大部分文件，手改的 AndroidManifest / strings.xml / 图标会丢，改完要么不再 init，要么记下手改内容重新打。

图标 / 应用名同步（不会自动跟 PC 同步）

PC 端图标源：src-tauri/icons/（icon.png 512×512 + tauri icon 生成的全套）
Android 用：src-tauri/gen/android/app/src/main/res/mipmap-*/ —— tauri android init 时从 src-tauri/icons/android/ 拷一份，之后不会自动跟 PC 同步
改图标：把整个 src-tauri/icons/android/（含 mipmap-* 和 values/ic_launcher_background.xml，别漏 values 子目录否则 Gradle 报 resource color/ic_launcher_background not found）拷到 gen/android/.../res/
应用名：src-tauri/gen/android/app/src/main/res/values/strings.xml 的 app_name / main_activity_title（默认是 productName，本项目手改为「知识库」）

软键盘 / viewport

AndroidManifest.xml activity 需 android:windowSoftInputMode="adjustResize"，否则配合 enableEdgeToEdge() 时 input 获得焦点也不弹键盘
index.html viewport 建议 width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover

🍎 移动端打包（iOS，需 macOS）

pnpm tauri ios init        # 一次性，生成 src-tauri/gen/apple/
pnpm tauri ios dev         # 模拟器 / 真机 dev
pnpm tauri ios build       # 生成 .ipa（需 Apple Developer Program 账号 + 描述文件）

签名走 Xcode 的 Signing & Capabilities（Team + Provisioning Profile），不像 Android 用 keystore
上架走 TestFlight / App Store Connect
本项目 iOS 链路尚未跑通（无 Mac 设备），相关任务见 docs/tasks/mobile-migration-tasks.md T-M005/T-M016/T-M018

版本管理（桌面 / 移动端两条独立版本线）

版本线	改哪里	tag	CI workflow	更新源
桌面（1.x）	三处同步：`package.json` / `src-tauri/Cargo.toml` / `src-tauri/tauri.conf.json` 的 version	`v..*`（例 `v1.9.0`）	`release.yml`	`update.json`
移动端（Android）（从 0.1.0 起）	只改一处：`src-tauri/tauri.android.conf.json` 的 `"version"`	`mobile-v..*`（例 `mobile-v0.1.0`）	`android.yml`	`update-mobile.json`

Tauri 2 构建 Android 时自动把 tauri.android.conf.json 合并覆盖到 tauri.conf.json，所以 Android APK 的 versionName 和编译进去的 package_info().version 都用这个独立的移动版本号，跟桌面 1.x 解耦。 不要把移动版本号往回调（Tauri 从它推 Android versionCode，倒退会让用户装不上）。

# 桌面（三处）
package.json:           "version": "1.0.0"
src-tauri/Cargo.toml:   version = "1.0.0"
src-tauri/tauri.conf.json: "version": "1.0.0"
# 移动端（一处）
src-tauri/tauri.android.conf.json: "version": "0.1.0"

CI 自动构建（推荐）

桌面三平台：.github/workflows/release.yml，推送 v*.*.* Tag 后自动构建 Windows/macOS/Linux 安装包。用 /release 命令一键发布，详见 release-publish 技能。
Android：.github/workflows/android.yml —— 触发方式：workflow_dispatch（手动，可选 debug / release）或推 mobile-v*.*.* tag（普通 push 到 master 不触发；前缀 mobile- 与桌面 v*.*.* 区分，互不打架）：
- debug：SDK debug keystore 自签名 → APK（侧载，仅 workflow_dispatch 选 debug 时）
- release（tag 触发 / workflow_dispatch 选 release）：从 Secrets 还原 kb-release.jks + key.properties → tauri android build --apk --aab 正式签名 → 产物起稳定名 Knowledge.Base_<移动版本>_android-arm64.apk（+ .aab，移动版本读 tauri.android.conf.json）→ tag 触发时附到本仓库 GitHub Release 草稿（tag = mobile-v<移动版本>）；同时设 TAURI_SIGNING_PRIVATE_KEY
- ⚠️ 被 tag 的那个 commit 消息不能含 [skip ci]，否则 tag push 也会被跳过
- 6 个 Secrets（ANDROID_KEYSTORE_BASE64 / ANDROID_KEYSTORE_PASSWORD / ANDROID_KEY_ALIAS / ANDROID_KEY_PASSWORD / TAURI_SIGNING_PRIVATE_KEY / TAURI_SIGNING_PRIVATE_KEY_PASSWORD）在主 bkywksj/knowledge-base + 备用 allebamala/knowledge-base 两个仓库都已配
- App 内"检查更新"闭环：release-publish 技能「移动端（Android）独立发布」流程把 release APK 放进 releases/mobile-v<版本>/ + 生成 update-mobile.json（指向 release 仓 raw / R2 上的 APK），App 的 check_mobile_update（src-tauri/src/commands/mobile_update.rs）读它拿直链。
iOS：CI 尚未接（需 Apple Developer 账号 + macOS runner，T-M020 待办）。

常见错误

错误做法	正确做法
不配置 release profile	添加 LTO + strip 优化体积
图标尺寸不全	使用 `tauri icon` 命令自动生成
版本号不同步	3 处版本号保持一致
不测试安装包	每次发布前在干净环境安装测试
不设置应用标识	identifier 使用反向域名格式
Rust 中启动子进程未设 `CREATE_NO_WINDOW`	打包后变 GUI 进程，所有 `Command::new()` 必须设 `creation_flags(0x08000000)`
`productName` 含中文导致 WiX MSI 打包失败	改用 NSIS (`"targets": ["nsis"]`) 或改 productName 为纯 ASCII
`bundle.targets` 设为 `"all"` 在 CI 上出错	CI 中通过 `--bundles` 参数指定，本地可用 `["nsis"]`
Android：项目路径含中文直接 `tauri android build`	必须 `env CARGO_TARGET_DIR="C:\\cargo-target\\<name>-android"` 前缀（NDK ld.lld 不认非 ASCII 路径）
以为发布 APK 还要连电脑	`tauri android build` 出的 APK 是独立的（`tauri://localhost` 读 APK 内资源），只有 `tauri android dev` 模式才连 dev server
手改 `gen/android/` 后又跑 `tauri android init`	init 会覆盖 AndroidManifest / strings.xml / 图标，手改的全丢；改完别再 init，或记下手改内容重新打
Android 权限只在 capabilities 里声明	AndroidManifest `<uses-permission>` 和 Tauri capabilities 是两套，摄像头/录音/联网两边都要声明
*同步 Android 图标只拷 `mipmap-`**	必须连 `values/ic_launcher_background.xml` 一起拷，否则 Gradle 报 `resource color/ic_launcher_background not found`
release APK 用 debug keystore	上架前必须用自己的 keystore（`key.properties` + `signingConfigs`），debug 签名不能上架且 keystore 丢了无法更新已上架应用
input 获焦不弹键盘（Android）	activity 加 `android:windowSoftInputMode="adjustResize"`

tauri-packaging

来源信息

安装方式

检查来源文件

同仓库更多 Skills

同仓库更多 Skills

Tauri 打包与分发

桌面端构建命令

打包配置 (tauri.conf.json)

基础配置

Windows 配置

macOS 配置

Linux 配置

图标生成

体积优化

典型打包体积

桌面端输出位置

便携版（Portable Zip）打包

便携模式触发条件

打 portable.zip 的方法

不做的事

🤖 移动端打包（Android）

dev 模式 vs build 模式（先搞清楚这个）

构建命令

🔴 项目路径含中文 → 必须设 CARGO_TARGET_DIR

APK / AAB 输出位置

Android 签名 — 本项目已配好（T-M019 一期）

AndroidManifest 权限（与 capabilities 是两套）

图标 / 应用名同步（不会自动跟 PC 同步）

软键盘 / viewport

🍎 移动端打包（iOS，需 macOS）

版本管理（桌面 / 移动端两条独立版本线）

CI 自动构建（推荐）

常见错误

Tauri 打包与分发

桌面端构建命令

打包配置 (tauri.conf.json)

基础配置

Windows 配置

macOS 配置

Linux 配置

图标生成

体积优化

典型打包体积

桌面端输出位置

便携版（Portable Zip）打包

便携模式触发条件

打 portable.zip 的方法

不做的事

🤖 移动端打包（Android）

dev 模式 vs build 模式（先搞清楚这个）

构建命令

🔴 项目路径含中文 → 必须设 CARGO_TARGET_DIR

APK / AAB 输出位置

Android 签名 — 本项目已配好（T-M019 一期）

AndroidManifest 权限（与 capabilities 是两套）

图标 / 应用名同步（不会自动跟 PC 同步）

软键盘 / viewport

🍎 移动端打包（iOS，需 macOS）

版本管理（桌面 / 移动端两条独立版本线）

CI 自动构建（推荐）

常见错误