Web 应用清单

Web 应用清单是一个 JSON 文件，告诉浏览器你的站点被安装为应用后应该如何表现。 它声明应用的标识（名称、图标、id）、安装边界（scope）、启动后的渲染方式 （display），以及快捷方式、share_target 等系统集成点。

一份最小可用的清单

{
  "name": "Weather Reports",
  "short_name": "Weather",
  "start_url": "/",
  "display": "standalone",
  "icons": [
    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

在每个希望可安装的页面上引入它：

<link rel="manifest" href="/manifest.webmanifest" />

规范把清单定义为通过 rel="manifest" 引入的应用清单；就格式本身而言，下面的每个字段 都是可选的。某个浏览器在提供安装之前究竟要求什么，是另一个与浏览器相关的问题： 见安装提示，不要假设规范已经替你回答了。

优先关注哪些字段

• 标识：name 与 short_name 决定安装提示 与主屏幕图标上的文字；id 固定应用身份，使 URL 变化不会 产生第二个安装实例。
• 入口与边界：start_url 是启动时打开的地址； scope 圈定哪些 URL 留在应用窗口内。
• 外观：display（配合 display_override）决定窗口形态； icons 与 theme_color/background_color 提供主屏幕图标与启动画面。

常见的出错点

• start_url 落在 scope 之外：应用启动后立刻离开自己的窗口。
• 清单的 content type 不对，或放在页面取不到的路径上。
• 改了 start_url 却没设 id，某些浏览器会把它当成另一个应用。
• 假定某个字段到处都被支持；支持度因字段、因平台而异。

下面每一页都带有自己的浏览器支持表与引用来源。

本节全部字段

scope 清单成员scope 成员是一个 URL 前缀，标记哪些页面属于已安装的 Web 应用；导航到它之外的页面仍保留应用窗口，但浏览器界面会重新出现。

start_url 清单成员start_url 是已安装 PWA 从主屏幕或应用列表启动时打开的同源 URL，也是给启动打分析标记的位置，并在缺少 id 时参与应用身份的推导。

id 清单成员id 是独立于 start_url 标识已安装 PWA 的字符串：启动 URL 可以更改，浏览器也不会把同一份清单当成第二个应用重复安装。

name 与 short_name 清单成员name 是已安装 Web 应用的完整标签，short_name 是主屏幕等狭窄位置使用的标签；Chromium 要求至少具备其中之一才会提供安装。

display 清单成员display 成员决定已安装的 Web 应用保留多少浏览器界面：fullscreen、standalone、minimal-ui 或 browser，四个值位于一条固定的回退链上。

display_override 清单成员display_override 按优先级列出显示模式，排在 display 回退链之前，让 PWA 在保留安全回退的同时请求 window-controls-overlay 或 tabbed 模式。

icons 清单成员icons 列出浏览器与操作系统用于已安装 PWA 的图像资源，含 src、sizes、type 与 purpose；它决定 Chromium 的可安装性以及 Android 上的 maskable 形状。

theme_color 与 background_color 清单成员theme_color 为已安装 PWA 的标题栏、状态栏与任务切换器着色；background_color 填充启动画面与首次绘制前的窗口。

screenshots 清单成员screenshots 成员列出标记为 wide 或 narrow 的图片，Android 上的 Chrome 94 与桌面端的 Chrome 105 在增强安装对话框中展示它们；Safari 与 Firefox 忽略该成员。

shortcuts 清单成员shortcuts 数组为已安装 PWA 图标的长按或右键菜单添加快捷操作条目，每一项直接打开一个作用域内的 URL，而不经过 start_url。

share_target 清单成员share_target 成员把已安装的 PWA 注册进系统分享面板，并通过 GET 或 multipart POST 把分享来的文本、URL 与文件送到作用域内的某个 URL。

file_handlers 清单成员file_handlers 把已安装的 PWA 注册为操作系统中指定 MIME 类型与扩展名的打开程序，随后由 window.launchQueue 把被打开的文件交给页面处理。

handle_links 清单成员handle_links 是 WICG 的一项提案，想让已安装的 PWA 请求浏览器在应用窗口中打开作用域内的链接。没有任何引擎实现它，Chrome 155 会直接丢弃该成员。

launch_handler 清单成员launch_handler 成员的 client_mode 决定再次启动已安装的 Web 应用时是聚焦现有窗口、让它导航，还是新开一个窗口；Chrome 与 Edge 110 实现了它。

lang、dir 与 *_localized 清单成员lang 与 dir 设定清单的默认语言和文字方向；*_localized 成员按语言携带 name、short_name、description 与 icons 的译文，Chrome 与 Edge 148 已实现。

related_applications 与 prefer_related_applicationsrelated_applications 按 platform、url 与 id 列出 PWA 的原生或 Web 对应应用；prefer_related_applications 让 Android 上的 Chrome 改为推荐其中一个。

edge_side_panel 清单成员Edge 专有的 edge_side_panel 成员及其 preferred_width 属性把 PWA 固定到 Microsoft Edge 侧边栏；Microsoft 已于 2026 年 7 月将其标记为弃用。

widgets 清单成员widgets 数组为 Windows 11 小组件面板注册 Adaptive Cards 小组件，由 PWA 的 Service Worker 通过 widgetinstall 等事件渲染和更新。

scope_extensions 清单成员scope_extensions 列出已安装 Web 应用视为作用域内的其他源，每个源都要用 web-app-origin-association 文件确认关联；Chrome 138 与 Edge 138 已发布。

tabbed 显示模式与 tab_strip 清单成员display_override 中的 tabbed 值让已安装 PWA 拥有自己的标签栏，tab_strip 成员则配置固定的主标签页与新建标签按钮。

categories 清单成员categories 成员是一个小写字符串数组，告诉应用商店和目录把 Web 应用归入哪些分区；浏览器会解析它，但不会据此渲染任何内容。

description 清单成员description 成员用一段文字说明 Web 应用做什么；Chrome 88 与 Edge 88 会在增强安装对话框里展示它，Firefox 与 Safari 解析后不做任何处理。

orientation 清单成员orientation 成员为已安装 Web 应用的窗口请求默认屏幕方向；Android 上的 Chrome 会遵循它，桌面浏览器与 Safari 则不会。

protocol_handlers 清单成员protocol_handlers 把已安装的 Web 应用注册为操作系统里 mailto、web+note 这类 URL 协议的处理程序；Chrome 96 与 Edge 96 仅在桌面端支持。

已安装的 PWA 如何获取清单更新Chrome 最多每天重新抓取一次已安装 PWA 的清单，把发生变化的清单排队到所有应用窗口关闭后再应用，桌面端与 Android 应用的字段集合并不相同。

延伸阅读

• 安装提示：浏览器在提供安装前要求什么。
• Service Worker：可安装、可离线应用的另一半。

← 返回参考总览。