macOS 使用 Capacitor 7 构建 Android 应用

2025-05-15
Avin Zheng
Capacitor, macOS

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 目录中。