协议处理程序注册让 PWA 处理自定义 URL schemes

为什么协议处理程序对 PWA 很重要

点击 mailto: 链接会打开邮件应用。点击 tel: 链接会打开电话应用。点击自定义 scheme（如 obsidian://）会打开特定应用。

今天，PWA 只能使用现有的 navigator.registerProtocolHandler() API 注册协议处理程序，这需要 JavaScript 运行且有平台特定限制。一个新兴的 WICG 提案为 PWA 添加了基于 manifest 的协议处理程序注册，允许它们以声明方式提供对 URL schemes 的支持。

根据 WICG discourse 上的提案，该功能"将允许 Web 开发者通过 web app manifest 中的属性将 Web 应用注册为 URL 协议处理程序"。这是截至 2026 年初的一个 Chrome origin trial。

当前状态：基于 JavaScript 的注册

在基于 manifest 的方法之前，协议处理程序注册需要 JavaScript：

// 用户必须先安装你的 PWA
if (navigator.registerProtocolHandler) {
  navigator.registerProtocolHandler('web+music', 'https://yourapp.com/open?url=%s', 'My Music App');
}

JavaScript API 的限制

• 无可发现性：用户在点击链接之前无法看到哪些应用处理哪些 schemes
• 平台特定 UI：权限提示因浏览器而异且可能令人困惑
• 需要脚本执行：站点必须加载并运行 JavaScript 才能注册
• 无 manifest 验证：无法编译时检查处理程序 URL 是否有效
• 生态系统集成不佳：操作系统级别的应用关联无法识别 Web 处理程序

基于 manifest 的方法：声明式注册

提议的基于 manifest 的方法在你的 manifest.json 中声明处理程序：

{
  "protocol_handlers": [
    {
      "protocol": "mailto",
      "url": "/compose?email=%s"
    },
    {
      "protocol": "web+music",
      "url": "/play?track=%s"
    },
    {
      "protocol": "web+note",
      "url": "/view?note=%s"
    }
  ]
}

优势

• 声明式：在 PWA 安装前可发现处理程序
• Manifest 验证：浏览器可以在 manifest 解析时验证处理程序 URL
• 更好的集成：可以挂接到操作系统级别的应用关联 UI
• 无脚本依赖：注册不需要 JavaScript 执行
• 更好的用户体验：更清晰的权限提示和处理程序选择

决策框架：你应该采用它吗？

这是实验性的。Chrome 有一个 origin trial；Safari 和 Firefox 没有公开实现。使用此评估表来决定：

实验性状态清单

发布前：

• [ ] 你已审查 WICG 提案和 Chrome 意向发布
• [ ] 你理解这是 origin trial 功能，可能会更改
• [ ] 你有针对不支持 manifest 处理程序的浏览器的回退策略
• [ ] 如果规范更改，你准备删除或更新处理程序
• [ ] 你的用例不依赖此功能实现核心功能

何时有意义

| 场景 | 建议 | |------|------| | 面向公众的 PWA 多样化用户 | 等待该功能在稳定浏览器中发布 | | 受控环境中的企业 PWA | 如果你需要自定义 schemes，参与 origin trial | | 个人工具或内部开发工具 | 可以安全实验；你控制环境 | | 市场广场列出的 PWA | 在多浏览器支持存在之前避免 |

证明采用合理性的用例

• 邮件客户端：安装时处理 mailto: 链接
• 笔记应用：通过 web+note 处理自定义 schemes（如 obsidian://）
• 内容工具：处理 web+article 或 web+bookmark schemes
• 开发工具：处理 web+debug 或自定义开发工具 schemes

安全和隐私考虑

Scheme 限制

浏览器将限制 PWA 可以注册哪些 schemes：

• 允许：mailto:、tel:、web+*（自定义 Web schemes）
• 阻止：http:、https:、file: 以及任何可能用于钓鱼的 scheme
• 站点特定：某些 scheme（如 web+banking）可能有额外的验证

用户同意流程

即使有基于 manifest 的注册，用户也必须选择加入：

1. 用户点击类似 web+music:track-id-123 的链接
2. 浏览器检查已安装 PWA 的处理程序注册
3. 浏览器提示用户："在 My Music App 中打开？"
4. 用户授予一次性许可
5. 未来链接直接打开

指纹识别担忧

协议处理程序注册可能用于指纹识别（检测安装了哪些应用）。浏览器可能会实现：

• 权限提示在用户交互之前不显示已安装的处理程序
• 处理程序注册的速率限制或配额
• 对隐私意识用户的处理程序发现选择退出

Origin trial 参与者的实现步骤

1. 启用 origin trial

如果你有 Chrome origin trial 令牌，将其添加到 HTML 中：

<meta http-equiv="origin-trial" content="YOUR_TOKEN_HERE">

2. 更新你的 manifest

{
  "protocol_handlers": [
    {
      "protocol": "web+music",
      "url": "/play?track=%s"
    }
  ]
}

3. 实现你的处理程序端点

// /play?track=track-id-123
export async function onRequestGet({ url, request }) {
  const trackId = url.searchParams.get('track');
  // 验证_track_ ID，重定向到完整体验
  return Response.redirect(`/tracks/${trackId}`, 302);
}

4. 跨浏览器测试

• Chrome（启用 origin trial）：应该可以工作
• Safari、Firefox：回退到 JavaScript 注册或显示"无处理程序"消息
• 移动浏览器：处理程序选择 UI 差异显著

5. 监控遥测

跟踪：

• 多少用户授予处理程序权限
• 哪些 schemes 使用最频繁
• 处理程序使用的浏览器/操作系统细分
• 从链接点击到应用安装的转化率

如何告诉用户

解释协议处理程序时：

在应用商店列表中

"此应用可以直接打开 web+music: 链接。安装后，点击 web+music: URL 将在此应用中打开。"

在应用设置中

"处理 web+music 链接：开/关"——选择退出处理程序注册的开关

权限提示出现时（如果浏览器显示的话）

"My Music App 想要处理 web+music: 链接。允许？"

协议处理程序的未来

WICG 提案处于早期阶段。可能的后续步骤：

1. Chrome 在稳定版中发布：origin trial 反馈和实现细化之后
2. Safari 和 Firefox 评估：采用取决于实现复杂性和安全审查
3. 规范稳定化：WICG 将提案推进到 W3C incubation 或正式规范
4. 生态系统工具：DevTools 显示已注册处理程序，linters 验证 manifest 条目

目前，这是实验性的。如果你构建生产 PWA，请实现基于 JavaScript 的注册作为回退，并考虑将基于 manifest 的注册作为参与测试的 Chrome 用户的增强功能。

这对你的 PWA 产品策略意味着什么

协议处理程序是增长和保留杠杆：

• 增长：用户在点击自定义 schemes 链接时发现你的应用
• 保留：你的应用成为其内容生态系统的默认处理程序
• 锁定：拥有自定义 scheme 工作流的用户依赖你的应用
• 发现：应用市场可以突出显示处理流行 schemes 的应用

对于生态系统 PWA（笔记、内容管理、开发工具），协议处理程序是与原生竞争的必备条件。对于消费者 PWA，在多浏览器支持出现之前，它们是锦上添花。

下一步

协议处理程序注册是深度链接的一半。另一半是 URL 路由健壮性——确保你的应用即使用户未登录、遇到网络错误或遇到过时内容也能优雅地处理深度链接。与健壮的路由结合，协议处理程序将你的 PWA 从网站转变为操作系统的一等公民。

不要在实验性功能上构建关键用户流程。但请进行实验、向 WICG 提供反馈，并为稳定浏览器中发布协议处理程序做好架构准备。用户期望原生级集成——这正是 PWA 的吸引力所在。