iOS端PWA内部链接跳转至Safari问题求助

清单文件(manifest.json) #

{
  "theme_color": "#202020",
  "background_color": "#ffffff",
  "display": "standalone",
  "orientation": "portrait",
  "start_url": "/",
  "name": "Example",
  "short_name": "EXP",
  "description": "A system for stuff",
  "icons": [
    {
      "src": "/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icon-256x256.png",
      "sizes": "256x256",
      "type": "image/png"
    },
    {
      "src": "/icon-384x384.png",
      "sizes": "384x384",
      "type": "image/png"
    },
    {
      "src": "/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

元数据配置 #

export const metadata: Metadata = {
  title: "Example",
  description: "The offical example page.",
  generator: "Next.js",
  manifest: "/manifest.json",
  keywords: ["exp", "stuff", "stuff"],
  authors: [{ name: "Gerald Ibra" }],
  appleWebApp: {
    capable: true,
    title: "Example",
    statusBarStyle: "black-translucent",
  },
};

export const viewport: Viewport = {
  width: "device-width",
  initialScale: 1,
  maximumScale: 1,
};

问题描述 #

在iOS设备（iPhone/iPad）上打开PWA应用"Example"时，内部链接点击后会跳转至外部Safari浏览器，而Android设备及桌面浏览器中，内部链接可正常在应用内导航。

复现步骤 #

• 在iOS设备上打开PWA应用"Example"
• 点击任意内部链接（如首页跳转至/about页面），观察到链接在Safari中打开，而非留在PWA应用内

预期行为 #

内部链接应在PWA应用内打开，维持manifest.json定义的独立运行体验。

额外上下文 #

• PWA基于Next.js开发，使用next-pwa包
• 已尝试Next.js的Link组件和普通a标签
• 问题仅出现在iPhone设备上

因项目为公司项目，使用虚构标题和描述保护信息

解决方案 #

1. 确保Next.js Link组件正确使用 #

Pages Router 用法：

import Link from 'next/link';

<Link href="/about" passHref>
  <a>关于我们</a>
</Link>

App Router 用法：

import Link from 'next/link';

<Link href="/about">关于我们</Link>

确保href使用相对路径，不要带完整域名。

2. 修复普通a标签跳转问题 #

如果必须使用普通a标签，添加点击事件阻止默认跳转，手动触发Next.js路由：

import { useRouter } from 'next/router';

const router = useRouter();

const handleInternalLink = (e: React.MouseEvent<HTMLAnchorElement>) => {
  const href = e.currentTarget.href;
  if (href.startsWith(window.location.origin)) {
    e.preventDefault();
    const path = href.replace(window.location.origin, '');
    router.push(path);
  }
};

// 使用示例
<a href="/about" onClick={handleInternalLink}>关于我们</a>

3. 补充iOS PWA配置 #

在根布局或文档组件中添加apple-touch-icon meta标签，确保iOS识别应用图标：

<meta name="apple-touch-icon" href="/icon-192x192.png" />

4. 检查next-pwa配置 #

确保next.config.js中next-pwa的scope设置为根路径，保证路由范围正确：

const withPWA = require('next-pwa')({
  dest: 'public',
  register: true,
  scope: '/',
  sw: 'service-worker.js',
});

module.exports = withPWA({
  // 其他Next.js配置项
});

5. 全局拦截链接跳转（终极方案） #

在_app.tsx或根布局中添加全局点击监听，统一处理所有内部链接：

import { useEffect } from 'react';

useEffect(() => {
  const handleLinkClick = (e: MouseEvent) => {
    const link = (e.target as HTMLElement).closest('a');
    if (!link) return;

    const href = link.href;
    const origin = window.location.origin;

    // 跳过外部链接、新窗口打开、下载链接
    if (href.startsWith(origin) && !link.target && !link.hasAttribute('download')) {
      e.preventDefault();
      const path = href.replace(origin, '');
      window.history.pushState({}, '', path);
      window.dispatchEvent(new PopStateEvent('popstate'));
    }
  };

  document.addEventListener('click', handleLinkClick);
  return () => document.removeEventListener('click', handleLinkClick);
}, []);

内容的提问来源于stack exchange，提问作者Gerald Ibra