Next.js PWA在iOS端启动闪屏不显示问题求助

1. 改用多尺寸启动图声明 #

iOS PWA 不支持单张启动图适配所有设备，Next.js Metadata 中的 appleWebApp.startupImage 字段无法满足多尺寸需求，需通过单独的 <link> 标签指定对应设备的启动图：

// 在 app/layout.tsx（App Router）或 pages/_document.tsx（Pages Router）中添加
export default function RootLayout({ children }) {
  return (
    <html lang="zh-CN">
      <head>
        {/* iPhone 14 Pro/Pro Max */}
        <link rel="apple-touch-startup-image" media="(device-width: 430px) and (device-height: 932px) and (-webkit-device-pixel-ratio: 3)" href="/splash_screens/iphone14pro.png" />
        {/* iPhone 13/12 系列 */}
        <link rel="apple-touch-startup-image" media="(device-width: 390px) and (device-height: 844px) and (-webkit-device-pixel-ratio: 3)" href="/splash_screens/iphone13.png" />
        {/* iPad 10.9 英寸 */}
        <link rel="apple-touch-startup-image" media="(device-width: 820px) and (device-height: 1180px) and (-webkit-device-pixel-ratio: 2)" href="/splash_screens/ipad10.png" />
        {/* 按需补充其他设备尺寸的启动图 */}
      </head>
      <body>{children}</body>
    </html>
  );
}

2. 验证图片配置 #

• 启动图必须放在 public/splash_screens 目录下，确保路径可直接访问
• 图片格式为 PNG，尺寸严格匹配对应设备的物理像素（而非逻辑像素），比如 iPhone 14 Pro 启动图尺寸为 1290×2796 像素
• 避免使用透明背景，背景色需与 manifest 中的 background_color 一致，防止启动时出现白屏

3. 统一 Manifest 与 Metadata 配置 #

• 调整 manifest.json 中的 background_color，使其与启动图背景色匹配，减少过渡白屏的视觉冲击
• 完善 Metadata 中的视口与苹果应用配置：

export const metadata = {
  viewport: "width=device-width, initial-scale=1, viewport-fit=cover",
  appleWebApp: {
    title: `Apple ${APP_DEFAULT_TITLE}`,
    capable: true,
    statusBarStyle: "black-translucent",
    // 移除 startupImage 字段，改用上述 link 标签配置
  },
};

4. 清除缓存重新部署 #

• 重新构建并部署应用后，先删除 iOS 主屏幕上已添加的 PWA
• 清除 Safari 缓存（设置 > Safari 浏览器 > 清除历史记录与网站数据）
• 重新将网站添加到主屏幕，测试启动闪屏效果

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