从 Chrome 122 开始,您可以订阅 scope_extensions 应用清单成员的源试用,这样,控制多个子网域和顶级网域的网站就可以作为单个 Web 应用呈现。本文档介绍了 Chrome 团队为何要引入此功能,以及您可能希望在何时使用此功能。
概览
某些 Web 应用具有多个源,例如,example.com 作为主应用,然后 space_1.example.com、…、space_n.example.com(有时与 special-example.com 结合使用)作为子体验,所有这些都位于主应用之下。这种类型的网站架构在渐进式 Web 应用中具有重要意义。限制包括无法跨源共享 Service Worker、任何类型的设备、本地存储空间和权限。此外,独立 PWA 中的跨域导航会显示一个窗口界面(“超出范围”栏),表明用户已离开 PWA 体验。您可以参阅多源网站中的渐进式 Web 应用和在同一网域上构建多个渐进式 Web 应用,了解如何解决其中一些问题。
借助 Scope Extensions API,Web 应用可以克服同源政策对此类网站架构带来的一些挑战。它允许 Web 应用将其范围扩展到其他源,以帮助实现统一的体验,前提是 Web 应用的主要源与关联的源之间达成协议。
目标
Scope Extensions API 的主要目标是让控制多个子网域和顶级网域的网站在 Web 应用界面和链接捕获方面表现为一个连续的 Web 应用。例如,让跨越 example.com.co.uk 和 support.example.com 的网站 example.com 尽可能像单个 Web 应用一样运行。

Scope Extensions 允许具有多个源的 PWA 在 Web 应用界面方面表现为连续的 Web 应用。
在实践中,这可以转化为两个更具体的目标:
- 跨域导航:允许用户在关联的源之间导航,而不会通过调用窗口界面告知用户他们正在离开 PWA,从而干扰用户体验。
- 跨域链接捕获:允许 Web 应用捕获用户对与其关联的网站的导航。
跨域范围内导航
默认情况下,当用户在独立 PWA 中跨源导航时,系统会显示一个窗口界面,指明他们正在离开 PWA 体验。在 Chrome 中,此界面由一个“超出范围”栏组成,其中包含新来源的网址。这会破坏用户体验,因为用户希望继续在同一应用环境中浏览,但他们可能会认为自己被带离了该环境。

当用户在独立 PWA 中跨不同源导航时,Chrome 中会显示“超出范围”栏。
借助 Scope Extensions,当用户导航到任何关联的源时,系统不会显示窗口界面,因此 PWA 会呈现为统一的体验。
跨域链接捕获
链接捕获是指应用捕获其范围内的链接的能力。此功能的实现方式因浏览器和操作系统而异。例如,在 ChromeOS 上的 Chrome 中,已安装 PWA 范围内的链接默认会打开一个浏览器标签页,并在地址栏中显示一个指示,表明有一个应用能够处理这些链接,从而允许用户选择接受从该点开始自动捕获链接。

ChromeOS 中某个标签页的 Chrome 地址栏片段,其中显示了链接可由 PWA 处理的视觉指示,以及记住该决定的选项。
如果用户点击 PWA 范围之外的链接(包括指向子网域或顶级域名的链接),系统不会将其识别为属于该 PWA。例如,链接将在浏览器标签页中打开,而不会向用户显示有应用能够处理该链接。借助 Scope Extensions API,您可以扩展 PWA 的范围,以便将关联的来源视为范围内的链接。
实现
实现范围扩展需要建立主源站与关联源站之间的关系。
声明关联的来源列表
向主 PWA 来源添加 scope_extensions Web 应用清单成员,使 Web 应用能够将其范围扩展到其他来源。
Web 应用清单 (https://example.com)
{
"id": "/",
"name": "Example",
"display": "standalone",
"start_url": "/index.html",
"scope_extensions": [
{ "type": "origin", "origin": "https://help.example.com" },
{ "type": "origin", "origin": "https://example.co.uk" },
{ "type": "origin", "origin": "https://help.example.co.uk" }
]
}
确认关联
列出的每个源都会使用 /.well-known/web-app-origin-association 配置文件确认与 Web 应用的关联。此文件需要命名为 web-app-origin-association,并在此确切位置提供,因为它是一个众所周知的 URI。
/.well-known/web-app-origin-association(关联的源)
{
"https://example.com/": {
"scope": "/"
}
}
该文件列出了与来源关联的 Web 应用。每个键都是 Web 应用的清单 ID,每个值都可以设置一个相对于关联来源的可选范围。如果您省略了范围,则默认为“/”。
演示
该演示包含两个网站:
- 主 PWA:通过其 Web 应用清单中的
scope_extensions成员声明关联来源列表的实际 PWA。 - 扩展范围内的源:位于主 PWA 范围之外,但在被主 PWA 列为关联源并通过其
web-app-origin-association文件确认关系后,与主 PWA 关联的源。
如需执行以下测试,您必须启用 about://flags/#enable-desktop-pwas-scope-extensions 标志(从 Chrome v115 开始提供)。
测试跨域导航
作为这些测试的前提条件,请在浏览器中打开主 PWA,将其作为 PWA 安装,然后打开它以在独立模式下运行。PWA 包含指向扩展范围内的源和扩展范围外的源的链接。

演示 PWA,其中包含指向扩展范围内的源站和不在扩展范围内的源站的链接。
默认跨域导航(不在扩展范围内)
- 在全屏 PWA 中,点击指向不在扩展范围内的源的链接。
- 因此,系统会执行导航并显示“超出范围”栏。

默认情况下,在独立模式下,PWA 的跨域导航会显示“超出范围”栏。
使用范围扩展(在扩展范围内)进行跨域导航
- 返回 PWA 的首页。
- 点击不在扩展范围内的来源的链接。
- 默认情况下,系统应显示“超出范围”栏,但由于范围扩展关联,系统不会显示该栏。

在使用 Scope Extensions 建立源关联后,跨域导航中不会显示“超出范围”栏。
测试跨域链接捕获

点击指向 PWA 关联来源的链接会在新标签页中打开该链接,并显示“在应用中打开”图标,以便用户选择启用自动链接捕获功能。
源试用
如果您想在应用中与真实用户一起测试此 API,可以通过源试用来实现。通过源试用,您可以获取与您的网域关联的测试令牌,从而与用户一起试用实验性功能。然后,您可以部署应用,并期望它在支持您要测试的功能的浏览器中运行(在本例中,该功能在 Chrome 121 到 126 中可用)。如需获取自己的令牌以运行源试用,请填写申请表单。
反馈
Chrome 团队正在征求有关此 API 实用性的反馈。为了帮助团队根据有关此 API 的实用性和当前版本未涵盖的新用例的反馈来改进此 API,请在 GitHub 上提交问题。
其他资源
- Scope Extensions API - 源试用
- Chrome 状态 - Web 应用范围扩展
- Web 应用范围扩展说明
- 实验意向
- Mozilla 标准立场
- Apple 标准立场
- Chromium bug
- 多源网站中的渐进式 Web 应用
- 在同一网域上构建多个渐进式 Web 应用
致谢
特别感谢此 API 的开发团队。Scope Extensions 由 Alan Cutter 和黄璐指定,并由 Matt Giuca 提供输入。该 API 由 Google Chrome 的 Alan Cutter 以及 Microsoft Edge 的 Hassan Talat、Kristin Lee 和 Lu Huang 实现。