Manifest protocol_handlers：为 PWA 注册自定义 URL 协议

发布于 2026-08-282026-08-28作者 Carey Gill · 编辑流程

一句话： manifest 的 protocol_handlers 成员将已安装的 PWA 注册为操作系统对某个 URL 协议（如 mailto:，或自定义的 web+ 前缀协议）的处理程序，使点击匹配链接——无论来自浏览器标签页、其他应用还是操作系统——都会带着该 URL 启动你的应用，而不是单纯导航。

这是什么

根据 MDN 的说明，protocol_handlers 是一个对象数组，每个对象包含必需的 protocol （要处理的协议，例如 mailto、ms-word 或 web+jngl）和必需的 url（应用作用域内的 HTTPS URL，其中 %s 占位符会被替换为完整的被点击 URL）。与操作系统的关联注册通常发生在安装时，但根据 MDN 的说明，也可以在应用已安装之后再完成该关联。

支持情况

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

浏览器 / 平台	支持	版本	置信度	来源	备注
Chrome (Android)	不支持	—	中	来源	¹
Chrome (Desktop)	支持	96	中	来源	—
Edge (Desktop)	支持	96	中	来源	—
Safari (iOS)	不支持	—	中	来源	²
Safari (macOS)	不支持	—	中	来源	³
Firefox (Desktop)	不支持	—	中	来源	⁴
Samsung Internet	不支持	—	中	来源	⁵

仅桌面端可注册。
Safari 未实现 `protocol_handlers` manifest 成员（MDN 兼容性表，2026-10-03 核对）。
Safari 未实现 `protocol_handlers` manifest 成员（MDN 兼容性表，2026-10-03 核对）。
桌面版 Firefox 不依据 manifest 安装 Web 应用，也未实现 `protocol_handlers`（MDN 兼容性表，2026-10-03 核对）。
Chromium 仅在桌面安装中提供 manifest 协议处理程序；Samsung Internet 未列出支持（MDN 兼容性表，2026-10-03 核对）。

源数据: /compatibility/protocol-handlers.json · 全球使用占比: 37 % (StatCounter 2026-05)

来源: 规范 · MDN · 最近核验 2026-06-24 · 置信度: 中 (由来源计算)

在实现该特性的浏览器中，基于 manifest 的 protocol_handlers 注册均仅限桌面端；此外还存在一个更早、独立的 navigator.registerProtocolHandler() API，可在页面中以命令式方式注册处理程序，且不要求安装。

如何使用

在 manifest 中声明协议与 URL 模板：

{
  "protocol_handlers": [
    {
      "protocol": "web+coffee",
      "url": "/coffee?type=%s"
    }
  ]
}

另外，MDN 为相关的、更早的 navigator.registerProtocolHandler() API 记录了一条命名规则：其 scheme 参数必须以 web+ 开头并至少跟一个小写 ASCII 字母（例如 web+coffee），或者必须是固定安全列表中的协议之一（如 mailto、bitcoin、magnet）。 manifest 的 protocol_handlers 页面本身并未对其 protocol 字段说明有此类命名限制。

安装并注册完成后，处理程序 URL 中的 %s 占位符会被以该处理程序协议开头的 URL 替换。

如何在运行时检测

根据 MDN 的说明，将协议与已安装应用关联通常在安装期间完成，但也可以在应用已安装之后再完成该关联。页面能够检测的是另一个独立的命令式方法 registerProtocolHandler() 是否存在，适用于希望在安装之外也提供注册入口的站点：

if ('registerProtocolHandler' in navigator) {
  navigator.registerProtocolHandler('web+coffee', '/coffee?type=%s');
} else {
  // 没有命令式注册 API——改为依赖 manifest 声明的 protocol_handlers
  // 关联，它会在安装时完成注册。
}

常见问题

基于 manifest 的 protocol_handlers 注册只有在应用已安装后才会生效——在普通浏览器标签页中打开的页面不会注册任何内容。
MDN 所记录的 web+ 前缀 / 安全列表命名规则适用于更早的 registerProtocolHandler() API 的 scheme 参数——其 manifest protocol_handlers 页面本身并未说明 protocol 字段受到同样的限制。
根据 MDN 的说明，url 成员必须位于应用的 manifest 作用域内并使用 HTTPS——不能指向跨源地址。
%s 占位符被替换为完整的被点击 URL，而不仅是解析后的负载——需要在处理路由中自行解析协议名之后的部分。

下一步

manifest: file_handlers 支持情况 —— 另一个将已安装 PWA 注册给操作系统的 manifest 成员，只是面向的是文件类型而非 URL 协议。
处理文件 —— 一篇相关指南，介绍如何为已安装 PWA 注册操作系统级别的文件关联。