适用场景：你已经有一个网页项目（前端/H5/Web App），想把它快速打包成一个安卓 APK，并且希望后续网页更新后，安卓端也能直接看到新版本。
本教程采用的是Capacitor + Android 壳 + 直接加载线上网页的方案。
1. 方案说明
这个方案的核心思路是：
- • 你的安卓 App 只是一个“壳”
- • 壳里面直接打开你部署好的网页地址
- • 所以网页一更新，安卓 App 重新打开或刷新后，也会看到新版本
- • 不需要每次前端改动都重新打一个 APK
这条路线适合：
- • 已经有现成网页项目
- • 想最快做出安卓 App
- • 希望复用现有前端代码
- • 暂时不想重写原生 Android
2. 先决条件：你首先要安装什么
在开始之前，机器上至少要有这些东西：
2.1 Node.js 和 npm
需要能运行前端项目、安装 Capacitor。
检查方式：
如果没有安装，请先安装 Node.js（建议使用 LTS 版本）。
2.2 Java JDK
Android 构建依赖 Java。
建议安装 JDK 21。
检查方式：
java -version
javac -version
Ubuntu / Debian 可参考：
sudo apt-get update
sudo apt-get install -y openjdk-21-jdk
安装后建议确认：
/usr/lib/jvm/java-21-openjdk-amd64/bin/java -version
并设置环境变量（当前 shell 临时生效）：
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
如果你的 Android / Capacitor 版本较新，而 JDK 太老，可能会遇到：
invalid source release: 21
这通常表示构建链路要求 Java 21，但你当前用的是更低版本的 JDK。
2.3 Android SDK / Command Line Tools
打 APK 需要 Android SDK。
至少要有：
- • Android SDK command line tools
- • platform-tools
- • 一个 Android 平台（如
platforms;android-34） - • build-tools（如
build-tools;34.0.0）
如果是 Linux 服务器/命令行环境，可以用 command line tools 安装。
示例流程：
mkdir -p /opt/android-sdk/cmdline-tools
cd /opt/android-sdk
wget -O cmdline-tools.zip https://dl.google.com/android/repository/commandlinetools-linux-13114758_latest.zip
mkdir -p /opt/android-sdk/cmdline-tools/latest
unzip -oq cmdline-tools.zip -d /opt/android-sdk/cmdline-tools/latest-tmp
mv /opt/android-sdk/cmdline-tools/latest-tmp/cmdline-tools/* /opt/android-sdk/cmdline-tools/latest/
rm -rf /opt/android-sdk/cmdline-tools/latest-tmp
设置环境变量：
export ANDROID_SDK_ROOT=/opt/android-sdk
export ANDROID_HOME=/opt/android-sdk
接受协议并安装基础包：
yes | /opt/android-sdk/cmdline-tools/latest/bin/sdkmanager --sdk_root=/opt/android-sdk --licenses
/opt/android-sdk/cmdline-tools/latest/bin/sdkmanager --sdk_root=/opt/android-sdk "platform-tools" "platforms;android-34" "build-tools;34.0.0"
2.4 Android Studio（可选但强烈建议）
如果你只是想命令行构建 debug APK，可以不装 Android Studio。
但如果你要：
- • 改图标
- • 改启动页
- • 配签名
- • 接入原生权限
- • 调试真机
那安装 Android Studio 会方便很多。
3. 在网页项目里接入 Capacitor
假设你的项目根目录已经存在，里面有前端代码。
3.1 安装 Capacitor 依赖
在项目根目录执行：
npm install @capacitor/core @capacitor/cli @capacitor/android --save-dev
如果项目根目录本身没有 TypeScript，但你想使用capacitor.config.ts，还需要：
npm install typescript --save-dev
如果没装 TypeScript，而你用了capacitor.config.ts，可能会报：
Could not find installation of TypeScript
4. 新建 Capacitor 配置文件
在项目根目录创建：
capacitor.config.ts
import type { CapacitorConfig } from '@capacitor/cli';
const serverUrl = process.env.CAP_SERVER_URL || 'http://你的网页地址';
const config: CapacitorConfig = {
appId: 'com.example.webapp',
appName: 'My Web App',
webDir: 'dist',
bundledWebRuntime: false,
server: {
url: serverUrl,
cleartext: true,
androidScheme: 'http',
},
android: {
allowMixedContent: true,
},
};
export default config;
字段说明
- •
appId：安卓应用包名，必须唯一 - •
appName：App 显示名称 - •
webDir：前端构建产物目录 - •
server.url：安卓壳要加载的网页地址 - •
cleartext: true：允许加载http页面（如果你是 HTTPS，可视情况关闭） - •
allowMixedContent: true：允许混合内容（如 HTTPS 页面中有 HTTP 资源）
正式上线建议尽量使用HTTPS 域名，不要长期依赖裸 IP + HTTP。
5. 初始化 Android 工程
在项目根目录执行：
执行成功后，会生成一个android/目录，这就是安卓原生工程。
6. 可选：在 package.json 里加常用脚本
你可以在package.json里添加：
{
"scripts": {
"android:init": "npx cap add android",
"android:sync": "npx cap sync android",
"android:open": "npx cap open android",
"android:run": "npx cap run android",
"android:copy": "npx cap copy android"
}
}
这样以后用起来更顺手。
7. 如果 Gradle 默认下载很慢，怎么换更快的源
首次构建时，Gradle 可能会下载自己的发行包，例如：
有时默认源很慢，可以把 wrapper 下载源改到更快的镜像。
编辑：
android/gradle/wrapper/gradle-wrapper.properties
例如把：
distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-all.zip
改成：
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.14.3-all.zip
然后再执行 Gradle 命令。
如果你所在网络访问官方 Gradle 源慢，这一步通常能明显提速。
8. 构建 debug APK
进入 Android 工程目录：
然后确保环境变量正确：
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export ANDROID_SDK_ROOT=/opt/android-sdk
export ANDROID_HOME=/opt/android-sdk
开始构建：
如果构建成功，通常会在下面这个路径看到 APK：
android/app/build/outputs/apk/debug/app-debug.apk
9. 常见报错与处理办法
9.1java: command not found
说明没装 JDK，或者JAVA_HOME没配好。
处理：
- • 安装 JDK
- • 确认
java -version - • 设置
JAVA_HOME
9.2JAVA_HOME is not set
说明环境变量没配置。
处理：
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
9.3invalid source release: 21
说明当前构建要用 Java 21，但你装的是更低版本（比如 Java 17）。
处理：
- • 安装 JDK 21
- • 把
JAVA_HOME指向 Java 21
9.4Could not find installation of TypeScript
说明你用了capacitor.config.ts，但根目录没装 TypeScript。
处理：
npm install typescript --save-dev
9.5 Gradle 下载非常慢
处理思路：
- • 换
gradle-wrapper.properties里的镜像源 - • 避免反复删缓存
- • 必要时先手工下载到缓存目录
10. 这个方案更新是怎么工作的
这是本教程最重要的一点。
因为你现在走的是：
“安卓壳直接加载线上网页”
所以更新机制是：
- • 你更新网页前端
- • 部署到服务器
- • 安卓 App 重新打开或刷新
- • 就会看到新版本
优点
- • 不用每次前端改动都重打 APK
- • 一套网页，多端复用
- • 上线快
缺点
- • 依赖网络
- • 更像 WebView 壳，而不是真正的纯原生 App
- • 录音、上传、权限、登录态要多做移动端验证
11. 后续可以继续做什么
把 debug APK 打出来之后，通常还会继续做这些：
11.1 改应用图标和名称
可以在 Android Studio 里做，也可以直接改 Android 工程资源。
11.2 做 release 签名包
debug APK 适合测试，不适合正式分发。
正式发布通常需要：
- • 创建 keystore
- • 配签名
- • 执行 release 构建
11.3 补权限
如果你的网页需要这些能力，要额外验证：
- • 麦克风
- • 相机
- • 文件上传
- • 下载
- • 通知
- • 剪贴板
11.4 把 IP 地址换成正式域名
如果你当前配置的是：
建议后续换成：
这样稳定性、可信度、兼容性都会更好。
12. 一套最简命令回顾
如果你想快速回顾，可以记住下面这套：
安装依赖
npm install @capacitor/core @capacitor/cli @capacitor/android --save-dev
npm install typescript --save-dev
初始化 Android
配环境变量
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export ANDROID_SDK_ROOT=/opt/android-sdk
export ANDROID_HOME=/opt/android-sdk
安装 Android SDK 基础包
yes | /opt/android-sdk/cmdline-tools/latest/bin/sdkmanager --sdk_root=/opt/android-sdk --licenses
/opt/android-sdk/cmdline-tools/latest/bin/sdkmanager --sdk_root=/opt/android-sdk "platform-tools" "platforms;android-34" "build-tools;34.0.0"
构建 debug APK
cd android
./gradlew assembleDebug
APK 产物路径
android/app/build/outputs/apk/debug/app-debug.apk
13. 总结
如果你的目标是：
- • 已有网页项目
- • 想尽快变成安卓 App
- • 并且希望网页更新后安卓端也跟着变
那么：
Capacitor + 安卓壳 + 线上网页直连
就是一条非常实用、很省事的路线。
它的特点是：
- • 开发成本低
- • 复用现有前端最多
- • 能快速产出 APK
- • 后续还能逐步增加原生能力
如果后面要做得更完整，再继续加：
- • 图标
- • 启动页
- • 权限
- • 签名 release 包
- • 正式域名
- • 更细的 WebView 优化
如果你是把这份文档交给别人照着做，建议再补一页：
- • 项目实际目录结构
- • 你们自己的前端构建命令
- • 你们线上网页正式地址
- • 是否需要登录、录音、上传等附加能力
