ZhenYu's 知识库

外观

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：全屏、无任何浏览器 UI
  • standalone：像原生 App，隐藏地址栏，保留系统状态栏（最常用）
  • minimal-ui：保留最小化的浏览器控件（前进/后退）
  • browser：普通浏览器标签页

icons 的 purpose

  • any：普通图标
  • maskable：maskable icon，为不同设备形状（圆形、圆角方形、水滴形）预留安全区域
  • 建议同时提供 any maskable，兼顾所有场景

安装条件（可安装性）

浏览器触发 "添加到主屏幕" 的条件：

  1. 使用 HTTPS（localhost 除外）
  2. 包含有效的 manifest.json
  3. 注册了 Service Worker 并有 fetch 事件处理器
  4. 提供 192x192 和 512x512 的 icon
  5. 包含 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" 按钮手动测试。