# Web 应用来源关联文件

> 来源如何用 well-known JSON 文件确认 scope_extensions 请求，内容包括文件位置、数据结构、解析失败和导航回退。

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

## 工作原理

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

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

:::caution
如果顶层键不是有效 URL，Chromium 解析器会忽略该条目并报告 `Associated app ignored. Manifest ID is not a valid URL.`。如果值不是对象，它会报告 `Associated app ignored, type object expected.`（[Chromium 解析器源码](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/components/webapps/services/web_app_origin_association/web_app_origin_association_parser.cc)）。
:::

## 示例

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

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

### 确认一个应用

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

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

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

### 使用 `display-mode` 时保留导航

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

```js
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 成员](/zh/reference/manifest/scope-extensions/)
- [id manifest 成员](/zh/reference/manifest/id/)
- [Scope Extensions for Web App Manifest（GitHub）](https://github.com/WICG/manifest-incubations/blob/gh-pages/scope_extensions-explainer.md)
- [display-mode（MDN）](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/display-mode)