107 lines
3.0 KiB
Markdown
107 lines
3.0 KiB
Markdown
# Android 打包说明（Capacitor 8）
|
||
|
||
本文说明在 **macOS** 上为本项目生成 **调试 APK** 的目录、命令与环境要求。
|
||
|
||
## 环境要求
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| Node.js | **≥ 22**（Capacitor CLI 要求；可用 `nvm use 22`） |
|
||
| JDK | **21**（`@capacitor/android` 使用 Java 21；本机若仅有 JDK 17 会编译失败） |
|
||
| Android SDK | 已安装，且 `android/local.properties` 中配置 `sdk.dir` 指向 SDK 根目录 |
|
||
|
||
可选：在 `~/.zshrc` 中设置 `JAVA_HOME`（指向 JDK 21）、`ANDROID_SDK_ROOT`，并把 `nvm` 默认版本设为 22，避免每次手动导出。
|
||
|
||
## 目录约定
|
||
|
||
- **项目根目录**：`myApp/`（即包含 `package.json`、`capacitor.config.ts` 的目录）
|
||
- **原生工程**：`myApp/android/`
|
||
- **调试 APK 输出**：`android/app/build/outputs/apk/debug/app-debug.apk`
|
||
|
||
## 打包步骤（调试 APK）
|
||
|
||
在终端中执行：
|
||
|
||
### 1. 进入项目根目录
|
||
|
||
```bash
|
||
cd /path/to/myApp
|
||
```
|
||
|
||
（将 `/path/to/myApp` 换为你本机实际路径，例如 `~/Desktop/ionic/myApp`。）
|
||
|
||
### 2. 构建 Web 资源
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
### 3. 同步到 Android 工程
|
||
|
||
必须使用 **Node 22**：
|
||
|
||
```bash
|
||
nvm use 22
|
||
npx cap sync android
|
||
cd android
|
||
```
|
||
|
||
### 4. 使用 Gradle 生成调试包
|
||
|
||
```bash
|
||
./gradlew assembleDebug
|
||
```
|
||
|
||
若曾切换过 JDK，可先执行 `./gradlew --stop` 再编译。若仅用 **Android Studio** 构建，请在 IDE 里把 Gradle JDK 也选为 21。
|
||
|
||
### 5. 获取 APK
|
||
|
||
构建成功后，调试包路径为：
|
||
|
||
```text
|
||
android/app/build/outputs/apk/debug/app-debug.apk
|
||
```
|
||
|
||
可将该文件传到手机安装，或使用：
|
||
|
||
```bash
|
||
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
||
```
|
||
|
||
（需在 `android` 目录下或写全路径。）
|
||
|
||
## 一键串联示例（复制后按需改路径）
|
||
|
||
```bash
|
||
cd ~/Desktop/ionic/myApp
|
||
npm run build
|
||
nvm use 22
|
||
npx cap sync android
|
||
cd android && ./gradlew assembleDebug
|
||
```
|
||
|
||
## `local.properties` 说明
|
||
|
||
Android Gradle 需要知道 SDK 位置。若仓库中未提交（通常被 `.gitignore` 忽略），请在 `android/local.properties` 中自行维护，例如：
|
||
|
||
```properties
|
||
sdk.dir=/Users/你的用户名/Library/Android/sdk
|
||
```
|
||
|
||
将 `sdk.dir` 改为本机 Android SDK 绝对路径。
|
||
|
||
## Release / 上架
|
||
|
||
调试包（`assembleDebug`）不可直接用于应用商店上架。上架需要：
|
||
|
||
- 配置 **Release 签名**（keystore）
|
||
- 使用 Android Studio：**Build → Generate Signed Bundle / APK**，或命令行 `assembleRelease` / `bundleRelease` 并配置签名
|
||
|
||
具体以 Google Play 要求与团队证书策略为准。
|
||
|
||
## 常见问题
|
||
|
||
- **`The Capacitor CLI requires NodeJS >=22`**：先执行 `nvm use 22` 再运行 `npx cap`。
|
||
- **`无效的源发行版：21` / Java 21 相关错误**：确认 `JAVA_HOME` 为 JDK 21（终端可 `echo $JAVA_HOME`、`java -version`）；或在 `android/gradle.properties` 中设置 `org.gradle.java.home`（见上文）。
|
||
- **SDK location not found**：检查 `android/local.properties` 中的 `sdk.dir` 是否正确。
|