# Web 应用清单

> 让站点可安装的 JSON 文件：一份最小可用清单、如何引入、哪些字段最要紧，以及每个字段的详解在哪。

import { CardGrid, LinkCard } from '@astrojs/starlight/components';

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

## 一份最小可用的清单

```json
{
  "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" }
  ]
}
```

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

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

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

## 优先关注哪些字段

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

## 常见的出错点

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

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

## 本节全部字段

<CardGrid>
<LinkCard title="scope 清单成员" href="/zh/reference/manifest/scope/" description="scope 成员是一个 URL 前缀，标记哪些页面属于已安装的 Web 应用；导航到它之外的页面仍保留应用窗口，但浏览器界面会重新出现。" />
<LinkCard title="start_url 清单成员" href="/zh/reference/manifest/start-url/" description="start_url 是已安装 PWA 从主屏幕或应用列表启动时打开的同源 URL，也是给启动打分析标记的位置，并在缺少 id 时参与应用身份的推导。" />
	<LinkCard title="id 清单成员" href="/zh/reference/manifest/id/" description="id 是独立于 start_url 标识已安装 PWA 的字符串：启动 URL 可以更改，浏览器也不会把同一份清单当成第二个应用重复安装。" />
<LinkCard title="name 与 short_name 清单成员" href="/zh/reference/manifest/name-short-name/" description="name 是已安装 Web 应用的完整标签，short_name 是主屏幕等狭窄位置使用的标签；Chromium 要求至少具备其中之一才会提供安装。" />
<LinkCard title="display 清单成员" href="/zh/reference/manifest/display/" description="display 成员决定已安装的 Web 应用保留多少浏览器界面：fullscreen、standalone、minimal-ui 或 browser，四个值位于一条固定的回退链上。" />
	<LinkCard title="display_override 清单成员" href="/zh/reference/manifest/display-override/" description="display_override 按优先级列出显示模式，排在 display 回退链之前，让 PWA 在保留安全回退的同时请求 window-controls-overlay 或 tabbed 模式。" />
<LinkCard title="icons 清单成员" href="/zh/reference/manifest/icons/" description="icons 列出浏览器与操作系统用于已安装 PWA 的图像资源，含 src、sizes、type 与 purpose；它决定 Chromium 的可安装性以及 Android 上的 maskable 形状。" />
<LinkCard title="theme_color 与 background_color 清单成员" href="/zh/reference/manifest/theme-background-color/" description="theme_color 为已安装 PWA 的标题栏、状态栏与任务切换器着色；background_color 填充启动画面与首次绘制前的窗口。" />
<LinkCard title="screenshots 清单成员" href="/zh/reference/manifest/screenshots/" description="screenshots 成员列出标记为 wide 或 narrow 的图片，Android 上的 Chrome 94 与桌面端的 Chrome 105 在增强安装对话框中展示它们；Safari 与 Firefox 忽略该成员。" />
<LinkCard title="shortcuts 清单成员" href="/zh/reference/manifest/shortcuts/" description="shortcuts 数组为已安装 PWA 图标的长按或右键菜单添加快捷操作条目，每一项直接打开一个作用域内的 URL，而不经过 start_url。" />
<LinkCard title="share_target 清单成员" href="/zh/reference/manifest/share-target/" description="share_target 成员把已安装的 PWA 注册进系统分享面板，并通过 GET 或 multipart POST 把分享来的文本、URL 与文件送到作用域内的某个 URL。" />
	<LinkCard title="file_handlers 清单成员" href="/zh/reference/manifest/file-handlers/" description="file_handlers 把已安装的 PWA 注册为操作系统中指定 MIME 类型与扩展名的打开程序，随后由 window.launchQueue 把被打开的文件交给页面处理。" />
	<LinkCard title="handle_links 清单成员" href="/zh/reference/manifest/handle-links/" description="handle_links 是 WICG 的一项提案，想让已安装的 PWA 请求浏览器在应用窗口中打开作用域内的链接。没有任何引擎实现它，Chrome 155 会直接丢弃该成员。" />
	<LinkCard title="launch_handler 清单成员" href="/zh/reference/manifest/launch-handler/" description="launch_handler 成员的 client_mode 决定再次启动已安装的 Web 应用时是聚焦现有窗口、让它导航，还是新开一个窗口；Chrome 与 Edge 110 实现了它。" />
	<LinkCard title="lang、dir 与 *_localized 清单成员" href="/zh/reference/manifest/localization/" description="lang 与 dir 设定清单的默认语言和文字方向；*_localized 成员按语言携带 name、short_name、description 与 icons 的译文，Chrome 与 Edge 148 已实现。" />
	<LinkCard title="related_applications 与 prefer_related_applications" href="/zh/reference/manifest/related-applications/" description="related_applications 按 platform、url 与 id 列出 PWA 的原生或 Web 对应应用；prefer_related_applications 让 Android 上的 Chrome 改为推荐其中一个。" />
	<LinkCard title="edge_side_panel 清单成员" href="/zh/reference/manifest/edge-side-panel/" description="Edge 专有的 edge_side_panel 成员及其 preferred_width 属性把 PWA 固定到 Microsoft Edge 侧边栏；Microsoft 已于 2026 年 7 月将其标记为弃用。" />
	<LinkCard title="widgets 清单成员" href="/zh/reference/manifest/widgets/" description="widgets 数组为 Windows 11 小组件面板注册 Adaptive Cards 小组件，由 PWA 的 Service Worker 通过 widgetinstall 等事件渲染和更新。" />
	<LinkCard title="scope_extensions 清单成员" href="/zh/reference/manifest/scope-extensions/" description="scope_extensions 列出已安装 Web 应用视为作用域内的其他源，每个源都要用 web-app-origin-association 文件确认关联；Chrome 138 与 Edge 138 已发布。" />
<LinkCard title="tabbed 显示模式与 tab_strip 清单成员" href="/zh/reference/manifest/tabbed-display/" description="display_override 中的 tabbed 值让已安装 PWA 拥有自己的标签栏，tab_strip 成员则配置固定的主标签页与新建标签按钮。" />
	<LinkCard title="categories 清单成员" href="/zh/reference/manifest/categories/" description="categories 成员是一个小写字符串数组，告诉应用商店和目录把 Web 应用归入哪些分区；浏览器会解析它，但不会据此渲染任何内容。" />
	<LinkCard title="description 清单成员" href="/zh/reference/manifest/description/" description="description 成员用一段文字说明 Web 应用做什么；Chrome 88 与 Edge 88 会在增强安装对话框里展示它，Firefox 与 Safari 解析后不做任何处理。" />
	<LinkCard title="orientation 清单成员" href="/zh/reference/manifest/orientation/" description="orientation 成员为已安装 Web 应用的窗口请求默认屏幕方向；Android 上的 Chrome 会遵循它，桌面浏览器与 Safari 则不会。" />
	<LinkCard title="protocol_handlers 清单成员" href="/zh/reference/manifest/protocol-handlers/" description="protocol_handlers 把已安装的 Web 应用注册为操作系统里 mailto、web+note 这类 URL 协议的处理程序；Chrome 96 与 Edge 96 仅在桌面端支持。" />
	<LinkCard title="已安装的 PWA 如何获取清单更新" href="/zh/reference/manifest/manifest-updates/" description="Chrome 最多每天重新抓取一次已安装 PWA 的清单，把发生变化的清单排队到所有应用窗口关闭后再应用，桌面端与 Android 应用的字段集合并不相同。" />
</CardGrid>

## 延伸阅读

- [安装提示](/zh/reference/installation/install-prompt/)：浏览器在提供安装前要求什么。
- [Service Worker](/zh/reference/service-worker/)：可安装、可离线应用的另一半。

← 返回[参考](/zh/reference/)总览。