PWA → 安卓 App

把一个已经在跑的 PWA（或任何前端网页）打包成能装在安卓手机上的 App。

核心：改前端不用重新打包安装。

---

这篇讲什么

你已经有一个网页版应用，跑在自己的服务器上，手机浏览器能打开。现在你想要它变成桌面上一个真正的图标——点开就是全屏的 App，没有浏览器地址栏。

这篇讲怎么做到，以及怎么做到之后日常改动不用重新打包。

最后一节是可选的：怎么做锁屏全屏来电那种原生推送——这是壳子唯一真正比网页多出来的能力。

不讲：怎么从零写一个 PWA、iOS 打包、上架应用商店。

前置要求：会用命令行。不需要懂安卓开发，不需要开发者账号，不需要实名认证。

---

一、最重要的一件事：让壳子"活着"

先说这个，因为它决定了后面所有事的体验。

Capacitor 默认会把你的前端构建产物（dist 目录）打包死在 apk 里。这意味着：以后改一个按钮的颜色，你都要重新构建、重新签名、重新传到手机、重新安装一遍。

大部分人做私人 App 会死在这一步。不是技术难，是烦到最后不想改了。

破解方法是一行配置——让原生壳子去线上读页面：

// capacitor.config.ts
import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.yourname.app',
  appName: '你的应用名',
  webDir: 'dist',
  server: {
    url: 'https://your-domain.com/',   // ← 关键：壳子去线上读
    cleartext: false,
    errorPath: 'offline.html'          // ← 服务器连不上时的兜底页，这个是打包在本地的
  }
};

export default config;

配完之后的分工变成这样：

代价要说清楚，别被这个方案骗了：

• 离线打不开。 所以 errorPath 那个兜底页必须配，否则断网就是一片白屏。
• 首屏依赖网络。 服务器慢，开屏就慢。
• server.url 必须是 HTTPS 且证书有效，否则壳子直接白屏，而且不会告诉你为什么。自签证书也不行——浏览器会弹警告让你点"继续"，壳子里没有那个按钮。

对私人应用来说这笔买卖非常划算：一次打包，之后前端随便改。

---

二、环境准备（一次性）

三样，全部免费，不需要注册任何账号（想做原生推送的话需要一个 Google 账号，见第八节，可选）：

1. JDK 21

注意版本。Capacitor 8 的 capacitor-android 模块要求 Java 21，用 JDK 17 会在构建时报 invalid source release: 21。Capacitor 6/7 用 17 即可——这是版本升级带来的变化，大部分现存教程还停在 17。

sudo apt install openjdk-21-jdk

2. Android SDK

不需要装完整的 Android Studio（那玩意几个 G，还要图形界面）。命令行工具就够：

下载 commandline-tools，解压后：

export ANDROID_HOME=$HOME/android-sdk
sdkmanager "platform-tools" "platforms;android-34" "build-tools;34.0.0"

把 ANDROID_HOME 写进 ~/.bashrc，省得每次导。

3. 签名钥匙（keystore）

自己生成，不经任何审核：

keytool -genkey -v -keystore my-app.keystore \
  -alias myapp -keyalg RSA -keysize 2048 -validity 10000

会问你密码和一堆信息（姓名、组织、城市），随便填，但密码要记住并且备份。

这把钥匙丢了的后果：以后打的包签名对不上，用户（也就是你自己）必须卸载重装才能升级，App 里的本地数据全部丢失。备份它，跟备份密码一样认真。

---

三、套壳

npm install @capacitor/core @capacitor/cli @capacitor/android
npx cap init "你的应用名" "com.yourname.app" --web-dir=dist
npx cap add android

然后写 capacitor.config.ts（见第一节），再：

npm run build      # 构建前端，产出 dist/
npx cap sync android

`cap s