【免费下载链接】Front-End-Checklist
🗂 The essential checklist for modern web development, for humans and AI agents
导读：本文围绕开源仓库 Front-End-Checklist 中的
pwa-installability规则展开，系统讲解让 Web 应用满足浏览器"可安装"最低标准（HTTPS、Web App Manifest、Service Worker、192×192 与 512×512 图标）的全部要点。读完本文，你将掌握从手写manifest.json、使用 Next.js App Router 生成 Manifest，到捕获beforeinstallprompt事件、设计 Maskable 图标的端到端实战方案，并能用 DevTools、Lighthouse 与 PWABuilder 对可安装性做可验证的审计。
一、规则背景：什么是 PWA 可安装性
Front-End-Checklist 仓库将pwa-installability归类为html/setup子类别的规则，定位为low 优先级、intermediate 难度、约 30 分钟完成。规则的核心定义（见 pwa-installability.mdx 与 SKILL.md）为：
The web app satisfies the browser's minimum PWA installability requirements: a valid web app manifest, a registered service worker, HTTPS, and maskable icons.
一个渐进式 Web 应用（PWA）在浏览器检测到它满足一组最低标准后即变为"可安装"。此时浏览器会显示页内安装提示（或地址栏安装按钮），用户可以将应用添加到主屏幕或任务栏，获得接近原生应用的体验，而无需经过应用商店上架流程。从仓库的证据来看，安装后的 PWA 相比纯浏览器访问具有更高的参与度与留存率——平均而言，安装用户的使用时长约为未安装用户的 3 倍（该数据来自规则文档的whyItMatters字段，属规则文档陈述，供评估参考）。
该规则在仓库中有一系列相互关联的兄弟规则，共同构成完整的 PWA 落地闭环，见 web-app-manifest.mdx、service-worker.mdx 与 https.mdx。
二、快速参考：四条硬性要求
规则文档给出的 Quick Reference 即最小可安装性清单，共四条，缺一不可：
- HTTPS：站点必须通过安全源（Secure Origin）提供服务，浏览器强制要求；本地开发可使用
localhost。 - Web App Manifest：一个合法、且从
<head>中链接的manifest.json，包含name、icons、start_url、display。 - Service Worker：注册一个带
fetch处理器的 Service Worker，离线时能返回 200 响应。 - 图标：至少提供 192×192 与 512×512 两种尺寸的 PNG 图标；面向 Android 还需提供 maskable（遮罩）变体。
Chromium 系浏览器在弹出安装提示前，还额外要求 Manifest 必须包含name（或short_name）、start_url、display以及至少一个合法图标。
最小安装性要求对照表
| 要求 | 具体内容 |
|---|---|
| HTTPS | 站点必须运行在安全源上（开发环境可为localhost） |
| Web App Manifest | 一个从<head>链接的合法manifest.json |
| Service Worker | 注册了带fetch处理器的 SW |
| 图标 | 至少 192×192 与 512×512 的 PNG 图标各一个 |
三、完整 Code Example：一份可直接上线的 manifest.json
规则文档提供了一份可直接复制到public/manifest.json的完整示例。这份示例除了四项硬性要求，还包含了screenshots字段——它对应现代安装体验中"展示应用界面预览"的能力，也是 PWABuilder 生成商店包时的加分项：
// public/manifest.json { "name": "Acme Dashboard", "short_name": "Acme", "description": "Track your metrics at a glance.", "start_url": "/", "scope": "/", "display": "standalone", "background_color": "#ffffff", "theme_color": "#3b82f6", "orientation": "any", "lang": "en", "icons": [ { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" }, { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" }, { "src": "/icons/icon-maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" } ], "screenshots": [ { "src": "/screenshots/desktop.png", "sizes": "1280x720", "type": "image/png", "form_factor": "wide", "label": "Dashboard on desktop" }, { "src": "/screenshots/mobile.png", "sizes": "390x844", "type": "image/png", "form_factor": "narrow", "label": "Dashboard on mobile" } ] }要点说明：
start_url与scope建议保持为/，保证整个应用都在安装范围内；规则 Code Review 环节专门强调要核对start_url 与真实应用根路径是否一致，不一致会导致安装后打开错误页面。purpose: "maskable"的图标专门服务 Android 平台遮罩裁剪（详见第五节）。screenshots的form_factor取wide（宽屏）与narrow（窄屏）分别覆盖桌面与移动端安装界面。
四、在 HTML 中链接 Manifest 与 iOS 兼容处理
Manifest 必须通过<head>中的<link rel="manifest">暴露给浏览器。规则文档同时给出了 iOS 专属的 Meta 标签——Safari 并不会读取 Manifest 中的这部分字段，需要单独声明：
<!-- index.html or layout.tsx --> <head> <!-- Manifest --> <link rel="manifest" href="/manifest.json" /> <!-- iOS meta tags (Safari does not read the manifest for these) --> <meta name="apple-mobile-web-app-capable" content="yes" /> <meta name="apple-mobile-web-app-status-bar-style" content="default" /> <meta name="apple-mobile-web-app-title" content="Acme" /> <link rel="apple-touch-icon" href="/icons/apple-touch-icon.png" /> <!-- Theme colour --> <meta name="theme-color" content="#3b82f6" /> </head>在 Next.js 项目中，这个"链接动作"通常由框架代劳。以本仓库 apps/web 为例，其全局元数据集中在 seo-metadata.ts，其中通过 Next.js 的 Metadata 对象声明了：
icons: { icon: '/favicon.svg', shortcut: '/favicon.svg', apple: '/apple-touch-icon.svg' }, manifest: '/site.webmanifest',也就是说，Next.js 会在渲染时自动生成对应的<link rel="manifest">与图标链接，开发者只需要把真实文件放进public/即可。仓库中实际的 Manifest 文件位于 apps/web/public/site.webmanifest，内容即为 Front-End-Checklist 站点自身的 PWA 声明（name、short_name、start_url: "/"、display: "standalone"以及 SVG 图标），可以作为真实项目落地形态的对照参考。
五、Display Modes：四种显示模式的含义
display字段直接决定安装后的启动体验，规则文档给出的对照如下：
| 模式 | 行为 |
|---|---|
standalone | 应用在独立窗口中打开，不显示浏览器 UI——最接近原生应用 |
minimal-ui | 类似 standalone，但保留最小化的浏览器导航控件 |
fullscreen | 无任何浏览器 UI，适合游戏与沉浸式体验 |
browser | 在普通浏览器标签页中打开（不被视为"已安装"） |
选择建议：业务类应用首选standalone；游戏、播放器等沉浸场景考虑fullscreen；browser与minimal-ui在多数现代产品中已较少采用。
六、Maskable 图标：Android 遮罩与安全区
Android 平台会对主屏幕图标套用平台形状（圆形、圆角方形 squircle 等）。若未提供 maskable 图标，平台只会简单缩放普通图标，常常出现难看的留白。而 maskable 图标铺满整个画布，由 Android 按形状进行裁剪。
安全区（Safe Zone）是关键约束：安全区为以图标最小边长的 40% 为半径的圆。主 Logo 或图形必须完整落在这个圆内，才能保证在任何形状裁剪下都不会被切到。对 512×512 图标而言：
512×512 icon — safe zone = circle of radius 204 px centred at (256, 256)即安全区圆心在 (256, 256)、半径 204px。可以在生成图标时用 Maskable.app 编辑器预览图标在每种 Android 形状下的最终呈现效果（规则文档推荐的工具，仓库 pwa-installability.mdx 的resources中亦有收录）。
七、Next.js App Router 的 Manifest 生成方式
在 Next.js 13+ App Router 项目中，可以不维护静态 JSON，而是通过app/manifest.ts以类型安全的方式动态生成 Manifest。规则文档给出的完整示例（含MetadataRoute.Manifest类型约束）：
// app/manifest.ts (Next.js 13+ App Router) import type { MetadataRoute } from 'next' export default function manifest(): MetadataRoute.Manifest { return { name: 'Acme Dashboard', short_name: 'Acme', description: 'Track your metrics at a glance.', start_url: '/', display: 'standalone', background_color: '#ffffff', theme_color: '#3b82f6', icons: [ { src: '/icons/icon-192.png', sizes: '192x192', type: 'image/png' }, { src: '/icons/icon-512.png', sizes: '512x512', type: 'image/png' }, { src: '/icons/icon-maskable-512.png', sizes: '512x512', type: 'image/png', purpose: 'maskable', }, ], } }MetadataRoute.Manifest返回值会被 Next.js 序列化为/manifest.json并自动注入<link rel="manifest">，同时获得 TypeScript 的字段校验。这与仓库中 seo-metadata.ts 使用Metadata对象声明manifest: '/site.webmanifest'的静态方式互为补充：前者适合动态化需求，后者适合纯静态文件。
八、Prompting the Install：捕获 beforeinstallprompt 事件
当应用满足可安装条件时，浏览器会触发beforeinstallprompt事件。最佳实践是捕获并延迟展示安装提示（例如用户完成关键操作后再弹出），而不是页面加载后立刻弹出：
let deferredPrompt: BeforeInstallPromptEvent | null = null window.addEventListener('beforeinstallprompt', (event) => { // Prevent the automatic mini-infobar on mobile event.preventDefault() deferredPrompt = event as BeforeInstallPromptEvent showInstallButton() }) async function triggerInstallPrompt() { if (!deferredPrompt) return deferredPrompt.prompt() const { outcome } = await deferredPrompt.userChoice console.info('Install prompt outcome:', outcome) // 'accepted' | 'dismissed' deferredPrompt = null hideInstallButton() } window.addEventListener('appinstalled', () => { console.info('PWA installed') hideInstallButton() })代码要点：
event.preventDefault()抑制移动端自动出现的小型信息栏（mini-infobar），把决定权交给产品逻辑；deferredPrompt缓存事件对象，prompt()只能调用一次，调用后需置空；userChoice返回的outcome取值'accepted' | 'dismissed'，可用于埋点统计；appinstalled事件在安装完成后触发，用于隐藏按钮并记录转化。
iOS 的例外
警告：iOS Safari不支持
beforeinstallprompt事件。
在 iOS 上，用户必须手动点击分享按钮 → "添加到主屏幕"。规则文档建议对 iOS 用户展示一个轻量的引导气泡，并通过navigator.userAgent或standalonemedia feature 检测是否处于 iOS / 已安装环境：
// 检测已安装：matchMedia('(display-mode: standalone)') const isInstalled = window.matchMedia('(display-mode: standalone)').matches九、Service Worker：可安装性的另一只脚
可安装性要求"注册了带fetch处理器的 Service Worker"，离线时能给出 200 响应。仓库配套规则 service-worker.mdx 给出了完整实现范式：Service Worker 作为浏览器与网络之间的可编程代理，缓存静态资源、削减重复访问的服务端往返（规则文档称可降低重复访问加载时间 50–90%），并在弱网/离线环境下保持应用可用。核心注册代码形如：
async function registerServiceWorker() { if ('serviceWorker' in navigator) { const registration = await navigator.serviceWorker.register('/sw.js', { scope: '/', }) // ... } } window.addEventListener('load', registerServiceWorker)注意注册时机放在load之后，避免与首屏关键资源竞争带宽。缓存策略上，规则文档建议采用"先网络、后缓存、最终回退到离线页"的兜底链路，并示范了 Workbox 的registerRoute用法。可安装性审计时只需确认 SW 已注册且具备fetch处理即可，离线兜底的深度优化可单独参照该规则。
十、Support Notes：跨浏览器差异与优雅降级
规则文档明确提醒两点工程化注意事项：
- 可安装性提示与安装 UX 因浏览器和平台而异，不要假设一套 Chromium 安装流程覆盖所有用户，必须在目标浏览器上逐一验证支持的安装流程；
- 当浏览器支持 Manifest 但不支持完整安装提示或 standalone 体验时，必须文档化优雅降级方案（例如保留"添加到主屏幕"引导、对 iOS 用户提示分享菜单路径等）。
这与仓库中 web-app-manifest.mdx 的 Support Notes 一脉相承：Safari、Chromium 与已安装应用上下文对 Manifest 字段的解释各不相同，需显式验证目标平台，并在浏览器忽略部分字段或仍需单独 Meta 标签时记录平台级回退方案。
十一、验证与审计：如何确认可安装性达标
规则文档提供了一套可直接执行的验证清单，分为自动化与人工两部分：
自动化检查
- 打开 DevTools →Application→Manifest，确认所有必填字段显示为绿色、无警告；
- 运行LighthousePWA 审计，确认 "Installable" 各项标准全部通过；
- 使用PWABuilder获取详细的可安装性报告，并生成面向 Microsoft Store、Google Play 的商店就绪安装包——这也正是规则
description中所描述的使用场景（auditing PWA readiness / preparing for store submission via PWA Builder）。
人工检查
- 在 Android 设备或 Chrome 桌面端访问站点，观察地址栏是否出现安装按钮；
- 安装后从主屏幕/任务栏启动，确认以
standalone窗口打开、无浏览器 chrome。
仓库内的规则配套
- 规则本体：pwa-installability.mdx（含 frontmatter 元数据、
relatedRules与sources引用） - Skill 速查卡：skills/pwa-installability/SKILL.md（Check / Fix / Explain / Code Review 四段式 AI 审计指令）
- 完整实现参考：skills/pwa-installability/references/rule.md
- 关联规则：web-app-manifest.mdx、service-worker.mdx、https.mdx
- 真实落地示例：apps/web/public/site.webmanifest 与 apps/web/lib/seo-metadata.ts
十二、落地清单：从零到可安装的一次性检查表
最后，将全文浓缩为可直接照做的 10 步检查单：
- 站点已启用 HTTPS（生产环境强制；本地开发可用
localhost）； - 提供
public/manifest.json，包含name、short_name、start_url、display； <head>中已通过<link rel="manifest">或框架 Metadata 链接 Manifest；- 提供 192×192 与 512×512 的 PNG 图标；
- 额外提供
purpose: "maskable"的 512×512 图标，且主图形位于半径 204px 的安全区内； start_url与真实应用根路径一致，scope覆盖全站；- 已注册带
fetch处理器的 Service Worker（建议在load事件后注册）； - 已捕获
beforeinstallprompt并在合适时机主动弹出安装提示； - 已为 iOS 补充
apple-mobile-web-app-*Meta 标签与手动添加引导； - DevTools、Lighthouse、PWABuilder 三项验证全部通过。
完成以上 10 步，你的应用即可同时满足浏览器安装提示与应用商店上架（Microsoft Store / Google Play）的前置条件，真正把 PWA 的安装体验从"能用"提升到"可审计、可上架、可转化"。
【免费下载链接】Front-End-Checklist
🗂 The essential checklist for modern web development, for humans and AI agents
相关推荐
WuWa-Mod：鸣潮游戏玩法重塑与深度自定义解决方案
WuWa Mod：鸣潮游戏玩法重塑与深度自定义解决方案 还在为《鸣潮》游戏中的技能冷却、体力限制、战斗节奏等问题困扰吗？想要摆脱游戏机制束缚，按照自己的方式享受
CANN/ge：ATC原始GE选项详解
ATC Raw GE Options 1. 概述 ATC 离线编译入口支持两类 GE compile option 输入： 显式命令行参数，例如 jit_com
Alibi完全指南：10个核心方法让机器学习模型变得透明
Alibi完全指南：10个核心方法让机器学习模型变得透明 Alibi是一个强大的开源Python库，专门用于机器学习模型的可解释性（Explainable AI
前端文档SSR
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
