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，某些浏览器会把它当成另一个应用。
• 假定某个字段到处都被支持；支持度因字段、因平台而异。

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

本节全部字段

Manifest scope已安装应用的围栏边界——域内 vs 域外、share_target、shortcuts 与 start_url。

start_urlPWA 启动时加载的入口 URL——scope 约束、UTM 追踪与深度链接处理。

idThe stable identity of an installed PWA, independent of start_url.

name 与 short_name安装提示、主屏幕图标、应用切换器与系统启动器中的完整标签与缩短标签。

显示模式（display）standalone、fullscreen、minimal-ui、browser——回退链与 display_override。

display_overrideAn explicit ordered fallback list that takes precedence over display.

图标与 maskable 图标主屏幕、启动画面与任务栏的图标数组——含 Android 异形图标的 maskable 图标。

theme_color 与 background_color将浏览器界面与启动画面染成品牌色——深色模式、meta 标签交互与平台说明。

截图（screenshots）更丰富安装对话框中的推广图片——可滚动轮播与 form_factor 指导。

快捷方式（shortcuts）系统长按与右键上下文菜单中的快捷操作跳转列表条目。

share_target将 PWA 注册到系统原生分享菜单，从其他应用接收分享的 URL、文本与文件。

file_handlersRegister the PWA as a handler for file types the OS can open with it.

handle_linksWhether in-scope links open in the installed app or the browser.

launch_handlerWhether a launch reuses an existing window or opens a new one.

Localizationlang, dir, and translations for a manifest that adapts to the user's locale.

related_applicationsPoint at native counterparts, and prefer_related_applications to favour them.

edge_side_panelOpt a PWA into Edge's side panel surface.

widgetsThe experimental widgets member for OS widget surfaces.

scope_extensionsExtend a PWA's scope across origins with the experimental scope_extensions member and its web-app-origin-association handshake.

Tabbed application mode（标签式应用模式）实验性的 tabbed display_override 取值，以及 tab_strip 成员的 home_tab 与 new_tab_button。

categories应用商店风格的分类提示；仅供目录使用的元数据，浏览器从不渲染。

description可选的应用商店文案，由更丰富的安装界面与商店列表展示。

orientation为已安装应用的窗口请求默认屏幕方向。

protocol_handlers把已安装应用注册为自定义 URL 协议的处理程序。

清单更新已安装的 PWA 如何获取清单变更，以及哪些字段不会就地更新。

延伸阅读

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

← 返回参考总览。