support PWA

2026-09-15 11:20:03 +08:00
parent 8a0f5b6775
commit c0894cbab1
42 changed files with 1204 additions and 2 deletions
@@ -0,0 +1,41 @@
+# TWA 构建说明
+
+本目录是 `gao.imyeyu.com` 的 Trusted Web Activity 工程。APK 只包含 Android 启动壳，业务页面始终从 `https://gao.imyeyu.com/` 加载，不把前端 `dist` 打进 APK。
+
+## 构建环境
+
+- JDK 17
+- Android SDK
+- Bubblewrap CLI 1.25.0
+
+在本机首次使用 Bubblewrap 时执行：
+
+```powershell
+pnpm --config.registry=https://registry.npmjs.org dlx @bubblewrap/cli@1.25.0 doctor
+```
+
+## 构建 APK
+
+首次构建正式版本时，先在本目录生成并妥善备份 release keystore：
+
+```powershell
+keytool -genkeypair -v -keystore .\android.keystore -alias gao-customer -keyalg RSA -keysize 2048 -validity 10000
+```
+
+```powershell
+pnpm --config.registry=https://registry.npmjs.org dlx @bubblewrap/cli@1.25.0 build
+```
+
+构建前请准备长期保存的 release keystore，并确认 `twa-manifest.json` 中的 `signingKey` 指向它。当前目录的 `signingKey` 是可提交的相对路径模板；本次验证 APK 使用的是本机调试签名，不能作为正式发布签名。
+
+构建完成后，用 release keystore 的 SHA-256 证书指纹更新 `../public/.well-known/assetlinks.json`，再发布前端 `dist`。TWA 只有在网站的 `/.well-known/assetlinks.json` 与 APK 包名、签名一致时，才会进入无地址栏的全屏模式。
+
+当前 `assetlinks.json` 中登记的是本机调试证书指纹，只能配合本次验证 APK 使用。正式发布前必须替换为 release 证书指纹；如果使用 Google Play，还要把 Play App Signing 证书指纹一并登记。
+
+## 前端发布顺序
+
+1. 先上传新版本 `dist/assets`。
+2. 再上传新的 `index.html`、Manifest 和其他静态文件。
+3. 最后检查 `https://gao.imyeyu.com/`、`/manifest.webmanifest` 和 `/.well-known/assetlinks.json`。
+
+`index.html` 不缓存，带哈希的 `/assets/` 长缓存。不要给前端资源增加 Service Worker 缓存，除非同时实现版本更新和回滚，否则会阻止 TWA 获取最新页面。