3.0 KiB
3.0 KiB
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. 进入项目根目录
cd /path/to/myApp
（将 /path/to/myApp 换为你本机实际路径，例如 ~/Desktop/ionic/myApp。）
2. 构建 Web 资源
npm run build
3. 同步到 Android 工程
必须使用 Node 22：
nvm use 22
npx cap sync android
cd android
4. 使用 Gradle 生成调试包
./gradlew assembleDebug
若曾切换过 JDK，可先执行 ./gradlew --stop 再编译。若仅用 Android Studio 构建，请在 IDE 里把 Gradle JDK 也选为 21。
5. 获取 APK
构建成功后，调试包路径为：
android/app/build/outputs/apk/debug/app-debug.apk
可将该文件传到手机安装，或使用：
adb install -r app/build/outputs/apk/debug/app-debug.apk
（需在 android 目录下或写全路径。）
一键串联示例（复制后按需改路径）
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 中自行维护，例如：
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是否正确。