Web 应用来源关联文件

有限可用不支持的浏览器： Firefox (Desktop)、Firefox (Android)、Safari (macOS)、Safari (iOS)说明文档

Web 应用来源关联文件允许来源确认某个 Web 应用可以把它纳入扩展作用域。来源要在 /.well-known/web-app-origin-association 提供这份 JSON 文件。

工作原理

应用 manifest 在 scope_extensions 中列出另一个来源。对方把应用的 manifest id 写成关联文件的顶层键，确认这次请求。可选的 scope 成员限制应用能在确认来源上接受的 URL 范围；解释文档规定其默认值为 /。

两端分别控制自己的声明。按照解释文档描述的配对方式，删除 manifest 条目或关联文件里的匹配条目都会移除这组配对。

警告

如果顶层键不是有效 URL，Chromium 解析器会忽略该条目并报告 Associated app ignored. Manifest ID is not a valid URL.。如果值不是对象，它会报告 Associated app ignored, type object expected.（Chromium 解析器源码）。

示例

第一个例子给出关联文件本身。

第二个例子保留普通的跨来源链接，因为显示模式不能说明关联是否成功。

确认一个应用

下面的文件确认 manifest id 为 https://app.example/id 的应用，并把确认来源上的可接受作用域限制为 /docs。

{
  "https://app.example/id": {
    "scope": "/docs"
  }
}

确认方拥有这份文件，因此要把它放在 https://support.example/.well-known/web-app-origin-association。

使用 display-mode 时保留导航

display-mode 媒体特性报告应用当前采用的显示模式。这个值不是关联成功信号，因此两个分支都保留普通链接作为导航路径。

const link = document.createElement('a');
link.href = 'https://support.example/docs';
link.textContent = '打开文档';

if ('matchMedia' in globalThis && matchMedia('(display-mode: standalone)').matches) {
  link.dataset.surface = 'standalone';
} else {
  link.dataset.surface = 'browser-fallback';
}

document.body.append(link);

回退分支不会猜测查询为何返回 false。跨来源 URL 仍然可用，由浏览器执行普通导航。

另请参阅

• scope_extensions manifest 成员
• id manifest 成员
• Scope Extensions for Web App Manifest（GitHub）
• display-mode（MDN）

规范

规范	状态
Web 应用清单：scope_extensions	说明文档

• 图例
• 支持
• 部分支持
• 需开启标志
• 不支持
• 未知

浏览器 / 平台	支持	版本	置信度	来源	备注
Chrome (Desktop)#	支持	138	高	来源	—
Chrome (Android)#	支持	138	高	来源	1
Edge (Desktop)#	支持	138	高	来源	2
Firefox (Desktop)#	不支持	—	高	来源	3
Firefox (Android)#	不支持	—	高	来源	45
Safari (macOS)#	不支持	—	高	来源	6
Safari (iOS)#	不支持	—	高	来源	78
Samsung Internet#	支持	30.0	高	来源	9
WebView (Android)#	支持	138	高	来源	10

1. 由 browser-compat-data 镜像自 Chrome 的数据推导。
2. 由 browser-compat-data 镜像自 Chrome 的数据推导。
3. browser-compat-data 未记录 Firefox 的支持。
4. browser-compat-data 未记录 Firefox for Android 的支持。
5. 由 browser-compat-data 镜像自 Firefox 的数据推导。
6. browser-compat-data 未记录 Safari 的支持。
7. browser-compat-data 未记录 iOS 版 Safari 的支持。
8. 由 browser-compat-data 镜像自 Safari 的数据推导。
9. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
10. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。

源数据: /compatibility/manifest-scope-extensions.json · 全球使用占比: 75 % (StatCounter 2026-09, CC BY-SA 4.0)

来源: 规范 · MDN · 最近核验 2026-10-03 · 置信度: 高 (由来源计算)