macOS 使用 Capacitor 7 构建 Android 应用

Node.js 环境

安装 Node.js

搜索 Homebrew 支持的 Node.js 软件包方案:

brew search node
libbitcoin-node node node@14 node@20 ✔ nodeenv
linode-cli node-build node@16 node_exporter nodenv
llnode node-sass node@18 ✔ nodebrew ode

推荐安装最新的 LTS 版本(Capacitor 7 需要 Node.js v20+ 版本),即 node@20

brew install node@20

添加环境变量到 Zsh 配置文件 ~/.zshrc 中,并重新执行配置文件:

echo 'export PATH="/usr/local/opt/node@20/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

查看安装的 Node.js 版本号:

node -v
v20.19.0

安装 pnpm

使用 npm 全局安装 pnpm:

npm install -g pnpm@latest-10

初始化 pnpm 配置:

pnpm setup

查看安装的 pnpm 版本:

pnpm -v
10.6.5

Android 环境

安装 Android Studio

下载安装最新版 Android Studio (这里是 Android Studio Meerkat | 2024.3.1)。

Android Studio 会自行安装最优版本的 JDK 和 Gradle,不需要手动安装 JDK 和 Gradle。

安装完 Android Studio 之后第一次打开时会引导安装 Android SDK,在引导界面按照默认引导安装好即可(这里是 Capacitor 7 支持的 API 35)。

JDK 环境变量

如果需要使用 Capacitor CLI 来构建应用,需要设置 Gradle JDK 环境变量(使用 Android Studio 构建应用不需要设置)。

在 Android Studio 的 Preferences > Build, Execution, Deployment > Build Tools > Gradle > Default Gradle JDK 设置中找到内置的 JDK 安装目录:

/Applications/Android Studio.app/Contents/jbr/Contents/Home

将内置的 JDK 环境变量添加到当前用户 bash 配置文件中:

# JAVA_HOME
echo 'export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"' >> ~/.zshrc
echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc

# CLASS_PATH
echo 'export CLASS_PATH="$JAVA_HOME/lib"' >> ~/.zshrc

# 重新执行配置文件
source ~/.zshrc

.zshrc 为 zsh 配置文件,如果使用的是 bash,则配置文件为 ~/.bash_profile

查看设置的 Java 环境变量:

echo $JAVA_HOME && echo $CLASS_PATH
/Applications/Android Studio.app/Contents/jbr/Contents/Home
/Applications/Android Studio.app/Contents/jbr/Contents/Home/lib

查看 Java 版本:

java -version
openjdk version "21.0.5" 2024-10-15
OpenJDK Runtime Environment (build 21.0.5+-13047016-b750.29)
OpenJDK 64-Bit Server VM (build 21.0.5+-13047016-b750.29, mixed mode)

SDK 环境变量

如果需要使用 Capacitor CLI 来构建应用,需要设置 Android SDK 环境变量(使用 Android Studio 构建应用不需要设置)。

添加环境变量到当前用户 bash 配置文件:

# Android SDK Location
echo 'export ANDROID_SDK_ROOT="$HOME/Library/Android/sdk"' >> ~/.zshrc

# avdmanager, sdkmanager
echo 'export PATH="$PATH:$ANDROID_SDK_ROOT/tools/bin"' >> ~/.zshrc

# adb, logcat
echo 'export PATH="$PATH:$ANDROID_SDK_ROOT/platform-tools"' >> ~/.zshrc

# emulator
echo 'export PATH="$PATH:$ANDROID_SDK_ROOT/emulator"' >> ~/.zshrc

# 重新执行配置文件
source ~/.zshrc

查看已经安装的打包工具:

ls $ANDROID_SDK_ROOT/build-tools
35.0.1 36.0.0

将最高版本的路径添加到环境变量 PATH 中:

# apksigner, zipalign
echo 'export PATH="$PATH:$ANDROID_SDK_ROOT/build-tools/36.0.0"' >> ~/.zshrc

# 重新执行配置文件
source ~/.zshrc

安装 Capacitor

使用 pnpm 安装依赖:

pnpm add -D -E @capacitor/cli
pnpm add -E @capacitor/core
pnpm add -E @capacitor/android

初始化 Capacitor 配置文件:

npx cap init <app-name> <appid> --web-dir www
  • <app-name> 为打包后生成的应用名。
  • <appid> 为应用 ID(格式类似于 com.example.appname )。
  • --web-dir 的值为要构建的 Web 项目目录(需要确保 index.html 在项目目录里面的顶层)。

如果是 Angular 项目构建的 Web 项目,默认构建输出的目录实际是 dist/<app>/browser ,可在 angular.json 中修改打包配置项 projects.<app>.architect.build.options.outputPath 的值为(之后构建输出的目录为 www ,且 index.html 会在输出目录里面的顶层):

{
  "base": "www",
  "browser": ""
}

创建 Android 项目:

npx cap add android

同步 web 项目文件到 Android 项目中去:

npx cap sync

在 Android Studio 中打开 Android 项目并初始化(第一次打开项目时,Android Studio 会自行初始化项目,等待完成即可):

npx cap open android

运行 Android 应用

在 Android Studio 菜单栏的 Tools > Device Manager > Add a new device > Create Virtual Device 中创建一个模拟器(比如 Medium Phone),点击 Next ,修改 API 版本为 API 35 ,在 System Image 中点击下载图标下载一个系统镜像文件,点击 Finish 完成模拟器创建。

打开模拟器完成系统初始化,之后可以使用 Capacitor CLI 在模拟器中运行应用:

npx cap run android

构建 Android 应用

使用 Android Studio 构建

打开 Android Studio,在菜单中点击 Build > Generate App Bundles or APKs > Generate APKs ,会在 android/app/build/outputs/apk/debug/ 目录中构建 debug 版本的 Android 应用(构建 debug 应用会默认使用 ~/.android/debug.keystore 签名应用)。

使用 Capacitor CLI 构建

如果要使用 Capacitor CLI 来构建应用,不仅要设置 Gradle JDK 和 Android SDK 环境变量,还需要配置密钥库和密钥才行。

在 Capacitor 配置文件 capacitor.config.ts (或者 capacitor.config.json ) 中添加相关配置:

{
  appId: 'com.example.app',
  appName: 'app',
  webDir: 'www',
  android: {
    buildOptions: {
      keystorePath: '/Users/xxx/.android/debug.keystore',
      keystorePassword: 'android',
      keystoreAlias: 'androiddebugkey',
      keystoreAliasPassword: 'android',
      releaseType: 'APK',
      signingType: 'apksigner',
    }
  }
}

注意 keystorePath 必须是绝对路径,不能使用 ~ 来表示用户目录。

使用 Capacitor CLI 来构建应用:

npx cap build android

构建生成的应用在 android/app/build/outputs/apk/release 目录中。

参考文献