150 lines
5.4 KiB
Markdown
150 lines
5.4 KiB
Markdown
# 构建
|
||
|
||
在 WSL（Ubuntu）中构建，产物为 Android APK。桌面端可用于本地调试。
|
||
|
||
## 1. 一次性环境准备
|
||
### 1.1 基础工具（已具备可跳过）
|
||
- Node.js 18+、Rust 1.75+（`cargo`）、`rustup`。
|
||
- Android 交叉编译目标：
|
||
```bash
|
||
rustup target add aarch64-linux-android armv7-linux-androideabi \
|
||
i686-linux-android x86_64-linux-android
|
||
```
|
||
|
||
### 1.2 桌面调试依赖（仅本地跑 desktop 时需要）
|
||
```bash
|
||
sudo apt-get update
|
||
sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev \
|
||
libsoup-3.0-dev librsvg2-dev libjavascriptcoregtk-4.1-dev pkg-config
|
||
```
|
||
> AI 请求用 rustls，不依赖系统 OpenSSL。
|
||
|
||
### 1.3 Android SDK / NDK / JDK
|
||
```bash
|
||
sudo apt-get install -y openjdk-17-jdk
|
||
# 下载 commandline-tools 到 ~/android-sdk，然后：
|
||
export ANDROID_HOME=$HOME/android-sdk
|
||
export NDK_HOME=$ANDROID_HOME/ndk/26.1.10909125 # 版本以实际为准
|
||
sdkmanager "platform-tools" "platforms;android-34" \
|
||
"build-tools;34.0.0" "ndk;26.1.10909125"
|
||
```
|
||
建议把 `ANDROID_HOME`、`NDK_HOME`、`JAVA_HOME` 写入 `~/.bashrc`。
|
||
|
||
### 1.4 Tauri CLI
|
||
```bash
|
||
cargo install tauri-cli --version "^2.0"
|
||
# 或使用项目本地：npm i 后用 npm run tauri
|
||
```
|
||
|
||
## 2. 安装依赖
|
||
```bash
|
||
cd /mnt/d/workbench/tauri-android-invoice
|
||
npm install
|
||
```
|
||
|
||
## 3. 测试
|
||
```bash
|
||
# 前端纯逻辑测试（autofill）
|
||
npm test
|
||
# Rust 逻辑测试（db + ai 解析）
|
||
cd src-tauri && cargo test --lib
|
||
```
|
||
当前用例：前端 1-1~1-3，Rust 2-1~2-5（数据库）、3-1~3-3（AI 解析）。
|
||
|
||
## 4. 桌面调试（可选）
|
||
```bash
|
||
npm run tauri dev
|
||
```
|
||
|
||
## 5. 构建 Android APK
|
||
```bash
|
||
# 首次初始化 Android 工程（生成 src-tauri/gen/android）
|
||
npm run tauri android init
|
||
|
||
# 构建 APK（debug）
|
||
npm run tauri android build --debug
|
||
# 或 release（需配置签名）
|
||
npm run tauri android build
|
||
```
|
||
产物路径：
|
||
```
|
||
src-tauri/gen/android/app/build/outputs/apk/
|
||
|
||
```
|
||
|
||
## 6. 生成签名密钥（release 必需）
|
||
debug 构建自动用调试签名，release 必须自备 keystore。
|
||
|
||
### 6.1 生成 keystore
|
||
用 JDK 自带的 `keytool` 生成（有效期约 27 年）：
|
||
```bash
|
||
keytool -genkeypair -v \
|
||
-keystore ~/invoice-release.jks \
|
||
-alias invoice \
|
||
-keyalg RSA -keysize 2048 -validity 10000
|
||
```
|
||
按提示设置 keystore 口令、密钥口令与证书信息，妥善保管该文件与口令（丢失将无法更新已上架应用）。
|
||
|
||
### 6.2 配置签名给 Gradle
|
||
在 `src-tauri/gen/android/`（执行过 `android init` 后生成）创建 `keystore.properties`：
|
||
```properties
|
||
storeFile=/home/<user>/invoice-release.jks
|
||
storePassword=你的keystore口令
|
||
keyAlias=invoice
|
||
keyPassword=你的密钥口令
|
||
```
|
||
确认 `src-tauri/gen/android/app/build.gradle.kts` 读取该文件并应用到 `release` signingConfig（Tauri 模板通常已生成，如无则手动补充）。
|
||
|
||
> 安全提示：`keystore.properties` 与 `*.jks` 含机密，务必加入 `.gitignore`，不要提交。
|
||
|
||
### 6.3 构建已签名 release
|
||
```bash
|
||
npm run tauri android build # 生成签名后的 release APK/AAB
|
||
```
|
||
## 7. 安装到设备
|
||
```bash
|
||
adb install -r <上面生成的 apk 路径>
|
||
```
|
||
|
||
## 8. 常见问题
|
||
- 缺少 `gobject-2.0`/`openssl.pc`：补装 1.2 的桌面依赖（仅桌面构建需要）。
|
||
- 扫码权限报 `barcode-scanner:allow-scan not found`：该权限只在移动端，已放入 `src-tauri/capabilities/mobile.json`，桌面构建不加载。
|
||
- 图标缺失导致 `generate_context!` 失败：确认 `src-tauri/icons/icon.png` 存在，可用 `npm run tauri icon <源图>` 生成全套。
|
||
- NDK 找不到：检查 `NDK_HOME` 是否指向真实存在的版本目录。
|
||
|
||
|
||
|
||
## 9. Windows 本地工具链（通过 mise 安装）
|
||
|
||
本仓库根目录的 `mise.toml` 固定了 Android 构建所需的工具链，均通过 [mise](https://mise.jdx.dev) 管理。
|
||
|
||
安装步骤：
|
||
```powershell
|
||
mise install # 安装 java(temurin-17) + rust(1.89)
|
||
mise trust # 首次需信任本目录的 mise.toml 以启用环境变量
|
||
```
|
||
|
||
工具链清单：
|
||
- JDK 17（`java = "temurin-17"`），Android/Gradle 需要 17+。
|
||
- Rust 1.89（`rust = "1.89"`），并已 `rustup target add` 四个 Android 目标
|
||
（aarch64/armv7/i686/x86_64-linux-android）。
|
||
- Android SDK 安装在 `D:\android-sdk`（平台 android-34、build-tools 34.0.0、
|
||
platform-tools、NDK 27.2.12479018、emulator + system-images;android-34;google_apis;x86_64）。
|
||
通过 `mise.toml` 的 `[env]` 注入 `ANDROID_HOME` / `NDK_HOME` 及 PATH。
|
||
- 模拟器 AVD：`tauri_test`（Pixel 6，Android 14）。启动：`emulator -avd tauri_test`。
|
||
|
||
> 说明：Windows 上 mise 的 vfox android-sdk 插件校验会失败，且 C 盘空间紧张，
|
||
> 因此 SDK 手动安装到 D 盘并用环境变量接入；JDK 因 GitHub 发布 CDN 在本网络不可达，
|
||
> 改用清华镜像下载后由 mise 离线安装（`MISE_PREFER_OFFLINE=1`）。
|
||
|
||
### 已知问题：360 安全卫士拦截构建
|
||
本机安装了 **360 安全卫士**（`ZhuDongFangYu` 主动防御）。它会拦截 cargo 新编译出的
|
||
build-script 可执行文件的运行，导致 `cargo build` 报 `拒绝访问 (os error 5)` 或卡死。
|
||
构建 Android 前需临时退出 360 主动防御，或将本仓库与 `~/.cargo`、`~/.rustup` 加入信任白名单。
|
||
|
||
### 前端测试
|
||
```powershell
|
||
npm test # 含 autofill 与 qrscan（二维码解码）用例
|
||
node tests/fixtures/generate-qr.mjs # 生成一张测试二维码图片 tests/fixtures/sample-qr.png
|
||
```
|