Next.js 15 iOS安装后startupImage（启动屏）不显示问题排查

架构老林

2026-6-15

问题

使用Next.js 15开发应用，此前启动屏配置正常，但升级到15.0.3后启动屏失效。应用可正常安装，manifest文件加载正常，图标显示正常。浏览器检查器中head标签里的apple-touch-startup-image链接均已正确注册，且图片存放在public文件夹可正常访问。所有配置看起来无问题，唯一差异是Next.js版本，请问是否遗漏了什么配置？

根布局文件/src/app/layout.tsx中的相关配置：

export const metadata: Metadata = {
...,
appleWebApp: {
    capable: true,
    statusBarStyle: "default",
    title: APP_DEFAULT_TITLE,
    startupImage: [
      {
        media:
          "screen and (device-width: 1024px) and (device-height: 1366px) and (-webkit-device-pixel-ratio: 2) and (orientation: portrait)",
        url: "/assets/apple-splash-2048-2732.jpg",
      },
      {
        media:
          "screen and (device-width: 1024px) and (device-height: 1366px) and (-webkit-device-pixel-ratio: 2) and (orientation: landscape)",
        url: "/assets/apple-splash-2732-2048.jpg",
      },
      ...
    ]
}

manifest文件src/app/manifest.ts代码：

export default async function manifest(): Promise<MetadataRoute.Manifest> {
  const cookieStore = await cookies();
  let appType: AppType = "user";

  if (cookieStore.get("app-type")?.value === "admin") {
    appType = "admin";
  } else if (cookieStore.get("app-type")?.value === "employee") {
    appType = "employee";
  }

  const getStartUrl = () => {
    switch (appType) {
      case "employee":
        return routes.employeePortal.root;
      case "admin":
        return routes.adminPortal.root;
      default:
        return routes.userPortal.root;
    }
  };

  return {
    name: "App name",
    short_name: "App name",
    description: "App description",
    start_url: getStartUrl(),
    display: "standalone",
    background_color: "#ffffff",
    theme_color: "#ffffff",
    icons: [
      {
        src: "/assets/manifest-icon-192.maskable.png",
        sizes: "192x192",
        type: "image/png",
        purpose: "any",
      },
      {
        src: "/assets/manifest-icon-192.maskable.png",
        sizes: "192x192",
        type: "image/png",
        purpose: "maskable",
      },
      {
        src: "/assets/manifest-icon-512.maskable.png",
        sizes: "512x512",
        type: "image/png",
        purpose: "any",
      },
      {
        src: "/assets/manifest-icon-512.maskable.png",
        sizes: "512x512",
        type: "image/png",
        purpose: "maskable",
      },
    ],
  };
}

可能的解决方案

核对Next.js 15.0.3版本变更：Next.js 15在元数据生成逻辑上可能有调整，重点查看官方更新日志中关于appleWebApp、启动屏相关的API变更，确认是否存在媒体查询解析、URL路径处理的行为变化。
验证启动图尺寸与媒体查询匹配：确保启动图的实际像素尺寸完全对应媒体查询中的参数（比如竖屏配置的2048x2732必须和device-width:1024px+dpr=2的计算结果一致），尺寸不匹配会被iOS忽略。
清除缓存重新测试：升级版本后，浏览器或iOS设备可能缓存了旧资源。清除浏览器缓存，删除iOS设备上的应用后重新安装，同时确保服务器未缓存旧的head元数据。
检查manifest背景色一致性：iOS启动时会先显示background_color，如果启动图加载延迟，可能被误认为失效。确保background_color与启动图背景色一致，同时验证启动图的加载速度。
手动添加meta标签测试：暂时移除metadata中的appleWebApp.startupImage配置，手动在根布局的head中添加<link rel="apple-touch-startup-image" media="..." href="...">标签。如果手动添加后启动屏正常，说明Next.js自动生成逻辑存在bug，可临时用手动方案替代，或向官方提交issue。
排查元数据冲突：确认没有第三方PWA插件或自定义代码覆盖了apple-touch-startup-image标签，避免配置被意外修改。

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