COOWIN Android PWA 安装页

这是一个面向 Android Chrome 的轻量 PWA 安装项目，用于将 COOWIN 官网安装到手机桌面，并以接近原生 APP 的独立窗口方式运行。

用户无需下载 APK，也无需进入应用商店，只需要扫描二维码、使用 Chrome 打开安装页并确认安装。

项目效果

扫描二维码
→ 使用 Android Chrome 打开安装页
→ 点击“安装到手机桌面”
→ 在 Chrome 系统窗口中确认安装
→ 等待系统后台完成安装
→ 手机桌面出现 COOWIN 图标

安装入口：

https://www.coowingroup.com/pwa-install/

v1.0.2 重点改进

Android Chrome 中，用户点击系统“安装”后，网页可能很快收到安装事件，但 WebAPK 生成、应用注册和桌面图标创建仍需要几秒钟。

因此，本版本不再立即显示“安装成功”，而是按以下状态提示：

Chrome 已接受安装请求
→ 系统正在后台创建并安装 COOWIN
→ 请勿重复点击
→ 等待约 12 秒
→ 返回手机桌面查看图标

这样可以避免网页已经提示成功，但桌面图标还没有真正出现所造成的误解。

功能特性

Android Chrome 自定义 PWA 安装按钮；
自动监听 beforeinstallprompt；
自动注册根目录 Service Worker；
扫码直达安装页面；
Android、微信内置浏览器和桌面浏览器状态识别；
安装请求提交后的等待状态提示；
Chrome 桌面快捷方式权限排查提示；
PWA 图标、普通图标和 Maskable 自适应图标；
Service Worker 仅缓存 PWA 安装页资源；
不缓存 WordPress、PHP 接口、登录状态和动态数据；
支持 SiteGround、Apache、WordPress 等常见部署环境。

技术组成

技术	用途
Web App Manifest	定义应用名称、图标、启动地址和显示模式
Service Worker	提供 PWA 注册及安装页静态资源缓存
`beforeinstallprompt`	调用 Android Chrome 的系统安装窗口
`appinstalled`	接收浏览器已经开始处理安装的事件
HTTPS	PWA 和 Service Worker 的安全运行环境
QR Code	将安装页地址快速传递到手机

项目目录

coowin-pwa-installer-v1.0.2/
├── .gitignore
├── CHANGELOG.md
├── README.md
│
├── deploy/
│   ├── manifest.webmanifest
│   ├── service-worker.js
│   │
│   ├── pwa-icons/
│   │   ├── icon-192.png
│   │   ├── icon-512.png
│   │   └── icon-maskable-512.png
│   │
│   └── pwa-install/
│       ├── index.html
│       └── assets/
│           ├── css/
│           │   └── style.css
│           ├── images/
│           │   └── coowin-pwa-qr.png
│           └── js/
│               └── install.js
│
└── snippets/
    ├── htaccess-snippet.txt
    └── wordpress-functions-snippet.php

文件说明

`deploy/manifest.webmanifest`

定义：

应用完整名称；
手机桌面短名称；
启动地址；
PWA 作用域；
独立窗口模式；
主题颜色；
192×192 和 512×512 图标；
Android Maskable 自适应图标。

`deploy/service-worker.js`

负责：

注册 PWA；
预缓存安装页及图标；
删除旧版本缓存；
仅拦截 /pwa-install/、/pwa-icons/ 和 Manifest；
不干扰原 WordPress 网站和动态业务数据。

`deploy/pwa-install/index.html`

Android PWA 专用安装页面，包含：

安装步骤；
自定义安装按钮；
当前状态提示；
二维码；
Chrome 权限排查提示。

`deploy/pwa-install/assets/js/install.js`

负责：

检测 Android Chrome；
注册 Service Worker；
捕获 beforeinstallprompt；
显示系统安装窗口；
处理用户接受或取消安装；
安装请求接受后显示等待状态；
避免过早提示“安装成功”。

`snippets/htaccess-snippet.txt`

提供 Apache 和 SiteGround 使用的补充配置：

设置 .webmanifest 文件类型；
禁止长期缓存 Service Worker；
声明 Service Worker 根目录作用域。

`snippets/wordpress-functions-snippet.php`

可选的 WordPress 接入代码，用于让官网其他页面也加载 Manifest 并注册 Service Worker。

安装页本身已经包含这些配置，第一次测试时不必修改 functions.php。

部署要求

服务器需要满足：

网站使用 HTTPS；
可以上传静态 HTML、CSS、JavaScript、PNG 和 Manifest；
service-worker.js 能放在网站根目录；
Android 手机使用 Chrome 打开；
Chrome 拥有“创建桌面快捷方式”权限。

当前项目已经按照以下域名配置：

https://www.coowingroup.com/

安装页面：

https://www.coowingroup.com/pwa-install/

上传到 SiteGround

第一步：备份

上传前建议备份：

/public_html/.htaccess

本项目不会覆盖 WordPress 的：

index.php
wp-config.php
wp-content/
wp-admin/
wp-includes/

第二步：上传部署文件

将 deploy/ 文件夹里面的所有内容上传到网站根目录。

注意：上传的是 deploy/ 里面的文件和目录，不是把 deploy 这一层作为网站目录上传。

上传完成后应当是：

/public_html/
├── manifest.webmanifest
├── service-worker.js
├── pwa-icons/
├── pwa-install/
├── index.php
├── wp-config.php
└── 其他 WordPress 文件

第三步：追加 `.htaccess`

打开网站根目录现有的 .htaccess，将：

snippets/htaccess-snippet.txt

中的代码追加进去。

不要使用该文件覆盖 WordPress 原有 .htaccess。

追加内容：

<IfModule mod_mime.c>
  AddType application/manifest+json .webmanifest
  AddType application/javascript .js
</IfModule>

<IfModule mod_headers.c>
  <Files "service-worker.js">
    Header set Cache-Control "no-cache, no-store, must-revalidate"
    Header set Service-Worker-Allowed "/"
  </Files>

  <Files "manifest.webmanifest">
    Header set Cache-Control "no-cache"
  </Files>
</IfModule>

第四步：验证文件

分别访问：

https://www.coowingroup.com/manifest.webmanifest
https://www.coowingroup.com/service-worker.js
https://www.coowingroup.com/pwa-icons/icon-192.png
https://www.coowingroup.com/pwa-install/

正确状态：

没有 403；
没有 404；
Manifest 显示 JSON 内容；
Service Worker 显示 JavaScript；
图标可以直接打开；
安装页样式、二维码和按钮正常。

Android 安装测试

使用 Android 手机扫描安装页二维码；
选择 Chrome 打开；
等待页面显示“已经可以安装”；
点击“安装到手机桌面”；
在 Chrome 系统窗口中点击“安装”；
页面显示“正在后台创建并安装 COOWIN”；
等待几秒钟，不要重复点击；
返回手机桌面查看 COOWIN 图标；
点击图标，确认以独立窗口打开官网。

安装后图标没有立即出现

这是 Android PWA 安装中可能出现的正常延迟。

用户点击“安装”后，Chrome 和 Android 仍可能继续执行：

接受安装请求
→ 生成或获取 WebAPK
→ 注册应用
→ 通知桌面启动器
→ 创建桌面图标

因此网页收到安装事件，不代表桌面图标已经在同一瞬间生成。

本项目会等待约 12 秒后再提示用户检查桌面。

Chrome 创建桌面快捷方式权限

在已经测试的手机上，权限位置是：

手机“设置”
→ 应用
→ 应用管理
→ Chrome
→ 权限管理
→ 创建桌面快捷方式
→ 允许

如果页面提示安装已经提交，但桌面一直没有图标，应优先检查这个权限。

不同品牌 Android 手机的名称可能略有不同，例如：

创建桌面快捷方式
添加桌面快捷方式
创建主屏幕快捷方式
添加应用图标到桌面

已经安装过，无法再次测试

同一个 PWA 已经安装后，beforeinstallprompt 通常不会再次触发。

重新测试前：

从手机卸载 COOWIN；
打开 Android Chrome；
进入“设置”；
进入“网站设置”；
进入“所有网站”；
搜索 coowingroup.com；
点击“清除并重置”；
关闭并重新打开 Chrome；
再次访问安装页。

安装按钮一直不可用

依次检查：

网站是否为 HTTPS；
是否使用 Android Chrome；
是否停留在微信内置浏览器；
Manifest 是否可以访问；
192×192 和 512×512 图标是否存在；
Service Worker 是否可以访问；
是否已经安装过 COOWIN；
是否曾经取消安装并被 Chrome 暂时抑制；
刷新页面并等待几秒；
查看 Chrome 菜单中是否有“安装应用”。

微信扫码后的处理

微信内置浏览器通常不能直接执行完整的 Chrome PWA 安装流程。

微信扫码后：

点击右上角菜单
→ 选择“在浏览器中打开”
→ 选择 Chrome
→ 返回安装页继续安装

WordPress 可选接入

安装页已经可以独立运行，不需要修改 WordPress。

希望官网首页和其他 WordPress 页面也加载 PWA 元数据时，可将：

snippets/wordpress-functions-snippet.php

中的代码追加到当前主题或子主题的 functions.php。

建议优先放入子主题，避免主题更新后代码丢失。

修改应用名称

编辑：

deploy/manifest.webmanifest

重点字段：

{
  "name": "COOWIN Composite Products",
  "short_name": "COOWIN"
}

name：安装窗口中的完整名称；
short_name：手机桌面图标下方的名称。

修改后需要：

更新 Service Worker 缓存版本；
清除 Chrome 网站数据；
卸载旧 PWA；
重新安装。

替换正式图标

当前项目使用临时占位图标。

替换：

deploy/pwa-icons/icon-192.png
deploy/pwa-icons/icon-512.png
deploy/pwa-icons/icon-maskable-512.png

要求：

文件	尺寸	用途
`icon-192.png`	192×192	Android 常规图标
`icon-512.png`	512×512	Android 高清图标
`icon-maskable-512.png`	512×512	Android 自适应图标

建议：

使用正方形 PNG；
主体不要紧贴边缘；
Maskable 图标四周预留安全区域；
不要使用过小的文字；
尽量使用正式品牌 Logo。

修改网站地址

本项目当前按照根域名部署。

需要改成其他域名时，至少修改：

deploy/manifest.webmanifest
deploy/pwa-install/index.html
deploy/pwa-install/assets/images/coowin-pwa-qr.png
README.md

二维码必须重新生成，并指向新的安装页 URL。

Service Worker 缓存更新

每次修改安装页的 CSS、JavaScript、图标或 Manifest 后，建议递增：

const CACHE_NAME = 'coowin-pwa-shell-v1.0.2';

例如：

const CACHE_NAME = 'coowin-pwa-shell-v1.0.3';

同时修改 index.html 中的资源版本：

style.css?v=1.0.3
install.js?v=1.0.3

以及 service-worker.js 里的预缓存地址。

这样能避免手机继续读取旧版缓存。

缓存策略说明

当前 Service Worker 只处理：

/manifest.webmanifest
/pwa-icons/
/pwa-install/

不会处理：

WordPress 页面；
PHP 接口；
用户登录状态；
表单提交；
数据库响应；
产品动态内容；
后台管理页面。

这样既保留 PWA 安装能力，又能避免缓存影响原网站更新。

已知限制

网页不能强制用户安装；
用户必须在系统窗口中确认；
网页无法精确判断桌面图标何时真正创建完成；
某些 Android 手机需要单独授权 Chrome 创建桌面快捷方式；
安装完成后桌面图标可能延迟几秒钟出现；
微信内置浏览器不适合作为最终安装浏览器；
iPhone 的安装流程与 Android Chrome 不同，本项目主要针对 Android。

本地预览说明

直接双击 index.html 只能查看页面样式，不能完整测试 PWA 安装。

PWA 完整测试需要：

HTTPS 网站；
正确的 Manifest；
Service Worker；
Android Chrome；
与 Manifest 相同来源的部署地址。

版本记录

v1.0.2

修正安装事件触发后过早显示“安装成功”；
增加后台安装等待状态；
增加 12 秒完成提示；
增加 Chrome 桌面快捷方式权限说明；
改进 Service Worker 预缓存容错；
完善中文 README 和 GitHub 项目结构。

v1.0.1

修复安装状态提示冲突；
增加应用列表和桌面图标排查提示；
增加静态资源版本号。

v1.0.0

完成 Android PWA 安装页；
增加 Manifest、Service Worker、自定义安装按钮；
增加二维码和临时图标。

安全说明

本项目：

不采集用户信息；
不上传手机数据；
不读取通讯录、相册或定位；
不请求摄像头、麦克风等敏感权限；
不包含统计脚本；
不包含第三方 JavaScript 库；
不修改 WordPress 数据库。

适用场景

除 COOWIN 官网外，这套结构也适合：

企业官网；
WordPress 网站；
内部管理工具；
PHP＋SQLite WebApp；
客户查询页面；
产品展示系统；
无需发布到 Google Play 的轻量应用。

Name		Name	Last commit message	Last commit date
deploy		deploy
snippets		snippets
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

COOWIN Android PWA 安装页

项目效果

v1.0.2 重点改进

功能特性

技术组成

项目目录

文件说明

deploy/manifest.webmanifest

deploy/service-worker.js

deploy/pwa-install/index.html

deploy/pwa-install/assets/js/install.js

snippets/htaccess-snippet.txt

snippets/wordpress-functions-snippet.php