iOS端PWA跳转同scope登录页时显示Safari控制栏如何解决

解决方案 #

你遇到的是iOS平台PWA适配的常见问题，可按以下步骤逐一排查修复：

• 补全iOS专属PWA元标签
  现有配置只覆盖了通用PWA规则，需在/scanner/和/scanner/login两个页面的head中新增iOS专属配置：

  <!-- 声明应用可全屏运行 -->
  <meta name="apple-mobile-web-app-capable" content="yes">
  <!-- 配置状态栏样式，配合viewport-fit=cover实现全屏适配 -->
  <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
  

• 修正manifest相关配置
  现有manifest缺少必填的启动地址配置，且要避免manifest加载失败的问题：
  1. 调整manifest.json内容，补充start_url字段：

  {
    "display": "standalone",
    "scope": "/scanner/",
    "start_url": "/scanner/"
  }
  

  2. 将两个页面的manifest引用路径改为绝对路径，避免login页面用相对路径请求manifest404：

  <link rel="manifest" href="/scanner/manifest.json">
  

• 调整重定向逻辑
  iOS PWA对服务端301/302重定向的识别兼容性较差，很容易判定为跳出应用范围从而触发Safari控制栏。优先改为客户端路由跳转（如前端框架路由的push/replace方法）实现未登录状态下跳转到登录页，避免服务端重定向。
• 清理缓存重试
  所有配置修改完成后，需先删除已经添加到iOS主屏幕的旧PWA应用，清理Safari浏览器缓存后重新添加，避免iOS缓存旧的manifest配置导致修改不生效。

内容的提问来源于stack exchange，提问作者O'Niel