manifest.json 配置
约 647 字大约 2 分钟
PWAmanifest
2026-04-08
什么是 Web App Manifest
manifest.json 是一个 JSON 文件,用于告诉浏览器你的 Web 应用可以作为 PWA 安装到用户设备上,以及安装后如何显示。它是 PWA 三大核心之一(另外两个是 HTTPS 和 Service Worker)。
引入方式
在 HTML 的 <head> 中通过 <link> 引入:
<link rel="manifest" href="/manifest.json" />
<meta name="theme-color" content="#4285f4" />关键字段
{
"name": "ZhenYu Knowledge",
"short_name": "KB",
"description": "个人知识库站点",
"start_url": "/?source=pwa",
"scope": "/",
"display": "standalone",
"orientation": "portrait",
"theme_color": "#4285f4",
"background_color": "#ffffff",
"lang": "zh-CN",
"dir": "ltr",
"icons": [
{
"src": "/icons/icon-192.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "any maskable"
},
{
"src": "/icons/icon-512.png",
"sizes": "512x512",
"type": "image/png"
}
],
"shortcuts": [
{
"name": "最新文章",
"url": "/blog/",
"icons": [{ "src": "/icons/blog.png", "sizes": "96x96" }]
}
],
"screenshots": [
{
"src": "/screenshots/home.png",
"sizes": "1280x720",
"type": "image/png",
"form_factor": "wide"
}
]
}字段说明
| 字段 | 必填 | 说明 |
|---|---|---|
name | ✅ | 应用全称,展示在安装提示中 |
short_name | ✅ | 简称,桌面图标下方显示 |
start_url | ✅ | 启动 URL,建议带上 ?source=pwa 便于数据分析 |
scope | 应用的导航范围,超出 scope 的链接会跳出 PWA | |
display | 显示模式:fullscreen / standalone / minimal-ui / browser | |
orientation | 屏幕方向:portrait / landscape | |
theme_color | 状态栏/浏览器 UI 颜色 | |
background_color | 启动画面背景色 | |
icons | ✅ | 图标数组,必须至少提供 192x192 和 512x512 |
shortcuts | 长按图标弹出的快捷菜单 | |
screenshots | 应用截图,用于安装对话框富展示 |
display 模式对比
fullscreen:全屏、无任何浏览器 UIstandalone:像原生 App,隐藏地址栏,保留系统状态栏(最常用)minimal-ui:保留最小化的浏览器控件(前进/后退)browser:普通浏览器标签页
icons 的 purpose
any:普通图标maskable:maskable icon,为不同设备形状(圆形、圆角方形、水滴形)预留安全区域- 建议同时提供
any maskable,兼顾所有场景
安装条件(可安装性)
浏览器触发 "添加到主屏幕" 的条件:
- 使用 HTTPS(localhost 除外)
- 包含有效的
manifest.json - 注册了 Service Worker 并有
fetch事件处理器 - 提供 192x192 和 512x512 的 icon
- 包含
name/short_name、start_url、display(需为 standalone 等非 browser 值)
自定义安装按钮
监听 beforeinstallprompt 事件拦截浏览器默认安装提示,改为自定义 UI:
let deferredPrompt = null;
window.addEventListener('beforeinstallprompt', (e) => {
e.preventDefault();
deferredPrompt = e;
document.querySelector('#install-btn').hidden = false;
});
document.querySelector('#install-btn').addEventListener('click', async () => {
if (!deferredPrompt) return;
deferredPrompt.prompt();
const { outcome } = await deferredPrompt.userChoice;
console.log(`用户${outcome === 'accepted' ? '同意' : '拒绝'}安装`);
deferredPrompt = null;
});
window.addEventListener('appinstalled', () => {
console.log('PWA 已安装');
});判断当前运行模式
const isStandalone =
window.matchMedia('(display-mode: standalone)').matches ||
window.navigator.standalone === true; // iOS Safari调试
Chrome DevTools → Application → Manifest,可查看解析结果与警告,并提供 "Add to home screen" 按钮手动测试。
