HTML制作TWA应用教程示例

本文详解了如何用纯HTML+PWA零修改前端代码构建符合Google严格规范的安卓TWA（Trusted Web Activity）应用，直击开发者最易踩坑的核心难点：从PWA端必须满足的standalone显示模式、HTTPS全站加密、Service Worker激活与theme-color一致性，到Android端必须使用TrustedWebActivityIntentBuilder构建Intent、精准匹配start_url与SW拦截路径、设置不透明色值、实现SplashScreenStrategy，再到最关键的签名验证与Digital Asset Links部署——任何一环（如assetlinks.json路径/格式/证书指纹/Activity名不匹配、HTTP子资源混用、Chrome版本低于72）都会导致TWA静默降级为Custom Tab，而日志几乎不报错；文末还提供了实用调试技巧，教你通过adb命令验证链接状态、监听连接失败回调、利用Chrome DevTools精准定位白屏根源，堪称TWA落地避坑指南。

直接用 HTML + PWA 就能跑 TWA，不需要改一行前端代码，但 Android 侧的配置和签名必须严格满足 Google 的校验规则——否则 TrustedWebActivityIntentBuilder 会静默失败，或降级为 Custom Tab。

确认你的 PWA 已通过 TWA 基础校验

TWA 不是“换个 Intent 就行”，它依赖 Web 端的可信声明。必须同时满足：

• manifest.json 中 "display": "standalone" 或 "minimal-ui"（不能是 browser）
• 主页面响应头或 包含 theme-color，且与 Android setToolbarColor() 一致（颜色不匹配会导致启动闪退）
• 站点已部署在 HTTPS 下，且所有子资源（图标、JS、SW）也走 HTTPS；HTTP 重定向到 HTTPS 不算数
• service-worker.js 已注册并激活，且 navigator.serviceWorker.ready 能 resolve（TWA 启动时会检查 SW 是否可用）

Android 侧用 TrustedWebActivityIntentBuilder 构建 Intent

别用 WebView 或普通 CustomTabsIntent，TWA 必须走专用 builder。关键点：

• 构造时传入的 URL 必须和 manifest.json 中 start_url 同源，且路径可被 Service Worker 拦截（例如 start_url: "/"，你就不能传 https://a.com/login）
• setNavigationBarColor() 和 setToolbarColor() 必须是不透明色值（0xFF000000 格式），带 alpha 会崩溃
• 如果需要 splash screen，必须提前调用 setSplashScreenStrategy() 并传入实现 SplashScreenStrategy 的对象，不能只靠 AndroidManifest 的 android:windowBackground
• 启动前务必检查浏览器支持：TrustedWebActivityServiceConnectionPool.isAvailable(context)，返回 false 说明设备没装 Chrome 或版本太低（

示例片段：

TrustedWebActivityIntentBuilder twaBuilder = new TrustedWebActivityIntentBuilder("https://your-pwa.com/")
    .setToolbarColor(0xFF2196F3)
    .setNavigationBarColor(0xFF000000)
    .setSplashScreenStrategy(new SplashScreenStrategy() { /* 实现 onShow / onDismiss */ });
mTwaLauncher.launch(twaBuilder, mSplashScreenStrategy, () -> {/* 成功回调 */});

签名与 Digital Asset Links 是最容易卡住的环节

Google Play 安装包签名后，必须在域名根目录部署 .well-known/assetlinks.json，且内容需与 APK 签名证书 SHA256 指纹、包名、TWA Activity 名完全匹配。常见坑：

• assetlinks.json 必须可被 https://your-pwa.com/.well-known/assetlinks.json 直接 GET 访问，返回 Content-Type: application/json，不能有 301/302 重定向
• SHA256 指纹必须来自你最终上传到 Play Console 的那个签名密钥（不是 debug keystore），可用 keytool -list -v -keystore your-release-key.jks -alias alias_name -storepass password -keypass password 提取
• Activity 名默认是 .MainActivity，但如果你改过 android:name，assetlinks.json 里 intent_filter 的 name 字段必须同步更新
• 验证是否生效：用 adb shell pm verify-link --re-verify your.package.name，再 adb shell pm get-links your.package.name 查状态

调试时别只看 Logcat，重点抓 TrustedWebActivityService 连接状态

TWA 启动失败往往不抛异常，而是静默 fallback 到 Custom Tab。真正线索在服务连接过程：

• 启动前确保 TrustedWebActivityServiceConnectionPool 已初始化，且 bindService() 成功（否则 mTwaLauncher.launch() 会直接回调失败）
• 监听 TrustedWebActivityCallback 的 onConnectionFailed()，里面会带具体错误码，比如 ERROR_BROWSER_NOT_FOUND 或 ERROR_ASSET_LINKS_VERIFICATION_FAILED
• Chrome DevTools 远程调试地址是 chrome://inspect → 选中对应 TWA 进程，但注意：只有成功进入 TWA 页面后才可见；若卡在白屏，大概率是 Asset Links 或 SW 加载失败

Asset Links 验证不通过、Service Worker 未激活、HTTPS 子资源混用 HTTP —— 这三处任一出问题，TWA 就会退化，而日志里可能只有一行 “Fallback to Custom Tabs”。

本篇关于《HTML制作TWA应用教程示例》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！