iOS关闭状态下PWA点击通知无法通过Clients.openWindow打开指定URL

问题场景 #

PWA在iOS 18.1.1系统中，仅当应用被完全关闭（滑动退出）时，点击通知会跳转到添加至主屏幕时的基础URL；应用处于后台/前台时，可正常跳转到指定路径，常规的notificationclick事件处理方案均无效。

核心原因 #

iOS冷启动PWA时，系统会优先加载主屏幕配置的基础URL，此时Service Worker中的clients.openWindow调用可能被系统启动逻辑覆盖，无法直接打开指定路径。需要结合通知payload传参+主页面启动时的参数处理绕开该限制。

具体解决方案 #

1. 发送通知时携带目标URL #

在通知的payload中添加data字段，明确指定要跳转的路径：

// Service Worker中发送通知的示例代码
self.registration.showNotification('通知标题', {
  body: '通知内容',
  data: {
    targetUrl: 'https://your-origin.com/specific-path' // 替换为你的目标路径
  },
  icon: '/icons/icon-192x192.png', // 必要的通知图标
  badge: '/icons/badge-72x72.png'
});

2. 修改Service Worker的notificationclick事件处理 #

优化事件逻辑，优先复用已有窗口，冷启动时尝试直接打开目标路径并做降级处理：

self.addEventListener("notificationclick", function (event) {
  event.preventDefault();
  const targetUrl = event.notification.data.targetUrl;
  event.notification.close();

  event.waitUntil(
    self.clients.matchAll({ type: "window", includeUncontrolled: true })
      .then((clientsArray) => {
        // 检查是否有已打开的PWA窗口，有则直接导航到目标路径
        const existingClient = clientsArray.find(client => client.url.startsWith(self.location.origin));
        if (existingClient) {
          return existingClient.navigate(targetUrl).then(() => existingClient.focus());
        }

        // 无现有窗口时，尝试直接打开目标路径
        return self.clients.openWindow(targetUrl).then(windowClient => {
          if (windowClient) {
            windowClient.focus();
          } else {
            // 降级处理：先打开基础URL，再导航到目标路径
            return self.clients.openWindow('/').then(client => {
              client?.navigate(targetUrl);
            });
          }
        });
      })
  );
});

3. 主页面添加冷启动跳转处理 #

在PWA的基础URL页面（如index.html）中添加脚本，处理冷启动时的参数：

// 主页面的脚本（放在DOMContentLoaded事件中）
document.addEventListener('DOMContentLoaded', () => {
  // 处理iOS 18支持的launchQueue API
  if ('launchQueue' in window) {
    launchQueue.setConsumer((launchParams) => {
      const targetUrl = launchParams.targetURL || launchParams.data?.targetUrl;
      if (targetUrl) {
        window.location.href = targetUrl;
      }
    });
  }

  // 兼容传统方式：检查URL参数
  const urlParams = new URLSearchParams(window.location.search);
  const targetUrl = urlParams.get('targetUrl');
  if (targetUrl) {
    window.location.href = targetUrl;
    // 移除参数避免重复跳转
    urlParams.delete('targetUrl');
    window.history.replaceState({}, document.title, `${window.location.pathname}${urlParams.toString() ? `?${urlParams.toString()}` : ''}`);
  }
});

注意事项 #

• 确保目标URL与PWA同源，clients.openWindow不支持跨域跳转
• 通知的data字段必须正确携带目标路径，避免拼写错误
• 检查PWA的manifest.json中start_url配置是否正确，确保基础URL能正常加载

内容的提问来源于stack exchange，提问作者Måns