无需登录 数据私有 本地保存

URL 协议处理演示 - 将 PWA 注册为 URL 处理器

PWA 开发工具 PWA URL协议 处理 演示
3
0
0
0

PWA URL 协议处理演示

配置 PWA 的 Protocol Handlers，让您的应用注册并处理自定义 URL 协议

协议处理器配置
web+
自定义协议需使用 web+ 前缀，或选择下方预设协议
web+myapp web+notes web+pwa mailto tel webcal
/
%s 为占位符，将被替换为编码后的原始协议 URL
用于浏览器权限提示中显示的应用名称
协议处理流程
1
用户点击协议链接

例如：web+myapp:some/data?id=123

2
操作系统/浏览器查找注册的处理程序

检测已安装的 PWA 是否在 manifest 中声明了该协议

3
浏览器弹出确认对话框

询问用户是否允许使用该 PWA 打开此协议链接

4
PWA 接收并处理 URL

导航到：/handle-protocol?url=web+myapp%3Asome%2Fdata%3Fid%3D123

5
PWA 内部解析原始 URL

通过 decodeURIComponent() 还原原始协议数据进行业务处理

Manifest 预览
{ // ... 其他 manifest 配置 ... "protocol_handlers": [ { "protocol": "web+myapp", "url": "/handle-protocol?url=%s" } ] }

将以上配置添加到您的 manifest.json 中

测试 URL 处理
原始协议 URL：
编码后（%s 替换值）：
PWA 内部导航 URL：
PWA 中解析还原：
浏览器能力检测
registerProtocolHandler API： 检测中...
Manifest protocol_handlers： 检测中...
PWA 安装支持： 检测中...
完整 manifest.json 示例
{ "name": "我的 PWA 应用", "short_name": "MyPWA", "start_url": "/", "display": "standalone", "theme_color": "#4f46e5", "background_color": "#ffffff", "icons": [ { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" }, { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" } ], "protocol_handlers": [ { "protocol": "web+myapp", "url": "/handle-protocol?url=%s" } ] }
PWA 中解析协议 URL

在 PWA 的处理页面中，使用以下代码解析传入的协议 URL：

// 从查询参数中获取编码的协议 URL const urlParams = new URLSearchParams(window.location.search); const encodedUrl = urlParams.get('url'); // 解码还原原始协议 URL const originalUrl = decodeURIComponent(encodedUrl); // 结果: "web+myapp:some/data?id=123" // 解析协议和路径 const [protocol, pathData] = originalUrl.split(':'); // protocol = "web+myapp" // pathData = "some/data?id=123" // 进一步解析参数 const [path, queryString] = pathData.split('?'); const params = new URLSearchParams(queryString || '');
安全注意事项
  • 验证来源：始终验证传入的协议 URL 是否来自可信来源
  • URL 白名单：限制可处理的协议和路径模式
  • 输入消毒：对解码后的 URL 进行严格的输入验证
  • XSS 防护：避免直接将协议 URL 插入 DOM
  • HTTPS 必须：PWA 和协议处理均要求 HTTPS 环境
常见问题 (FAQ)

PWA URL 协议处理是一项允许已安装的 PWA 注册处理特定 URL 协议的功能。当用户在操作系统或浏览器中点击某个协议链接（如 web+myapp:some/path）时，系统会自动唤起对应的 PWA 来处理该链接。这需要在 manifest.json 中配置 protocol_handlers 字段。该功能在 Chrome 96+ 和 Edge 96+ 中得到支持。

目前支持的协议分为以下几类：

  • web+ 前缀自定义协议：如 web+myapp、web+notes 等，这是专门为 Web 应用保留的自定义协议命名空间。
  • 系统预设协议：包括 mailto（邮件）、tel（电话）、sms（短信）、webcal（日历）等。
  • 部分浏览器还支持 bitcoin、ethereum 等加密货币协议。

%s 是 URL 模板中的占位符，会被替换为经过 URI 编码 的完整协议 URL。例如，用户点击 web+myapp:path/data?id=1，该 URL 经过 encodeURIComponent() 编码后变为 web+myapp%3Apath%2Fdata%3Fid%3D1，然后替换到模板中的 %s 位置。在 PWA 内部，您需要使用 decodeURIComponent() 来还原原始 URL。

用户可以通过多种方式触发协议处理：点击网页中的协议链接（<a href="web+myapp:...">）、在浏览器地址栏直接输入协议 URL、从其他应用（如邮件客户端、文档编辑器）中点击协议链接、或通过操作系统的自定义 URL 方案唤起。首次触发时，浏览器会弹出确认对话框询问用户是否允许该 PWA 处理此类链接。

  1. 确保 PWA 已正确安装（需要 HTTPS 环境）。
  2. 在 manifest.json 中配置 protocol_handlers。
  3. 创建一个包含协议链接的测试页面（如 <a href="web+myapp:test">测试链接</a>）。
  4. 在浏览器中点击该链接，观察是否弹出协议处理确认对话框。
  5. 在 Chrome 中，可以在 chrome://settings/content/handlers 管理已注册的协议处理程序。

两者都可以注册协议处理，但有以下关键区别：

  • registerProtocolHandler：通过 JavaScript 在运行时动态注册，需要用户手势触发，注册后对所有该浏览器的访问生效（不限于 PWA）。
  • manifest protocol_handlers：在 PWA 的 manifest 中静态声明，仅在 PWA 安装后生效，与 PWA 生命周期绑定。这是推荐的 PWA 协议处理方式。
  • 两者可以配合使用，但 protocol_handlers 是 PWA 场景下的最佳实践。

截至 2024 年：

  • Chrome 96+：全面支持 manifest protocol_handlers（桌面和 Android）
  • Edge 96+：支持（基于 Chromium）
  • Opera 82+：支持（基于 Chromium）
  • Safari：目前不支持 manifest protocol_handlers，但支持部分 registerProtocolHandler 功能
  • Firefox：有限支持，主要通过 registerProtocolHandler

建议使用前进行浏览器兼容性检测，并提供降级方案。

  • 在 Chrome 中访问 chrome://settings/content/handlers 查看已注册的协议处理程序。
  • 检查 manifest.json 中的 protocol_handlers 配置格式是否正确。
  • 确保 PWA 已正确安装（检查 Chrome DevTools > Application > Manifest）。
  • 查看浏览器控制台是否有协议处理相关的错误信息。
  • 测试时使用不同的协议链接格式，确认 URL 编码/解码逻辑正确。
🔧 相关工具