驯服 iOS Safari PWA 状态栏 — 为什么动态主题切换不起作用以及如何解决

起因

在开发支持深色/浅色主题切换的 PWA 时，我理所当然地认为 iOS 状态栏应该跟随主题变化。毕竟，PWA 就应该像原生应用一样，对吧？

但现实并非如此。首次启动时，状态栏颜色确实正确更新了；然而在运行期间切换主题时，状态栏却固执地拒绝任何变化。

罪魁祸首是 apple-mobile-web-app-status-bar-style 这个 meta 标签——它只在 PWA 启动时读取一次。之后无论你如何修改、删除或重建这个标签，iOS 都会直接忽略。

这是 WebKit 的一个已知限制，Apple 至今未曾修复。

第一次尝试——动态更新 Meta 标签

我的第一反应似乎很合理：每次用户切换主题时，更新 meta 标签的 content 属性。

function updateThemeColorMeta(theme: Theme) {
  const themeColor = theme === 'dark' ? '#000000' : '#FFFEF9';
  const statusBarStyle = theme === 'dark' ? 'black' : 'default';

  const themeColorMeta = document.querySelector('meta[name="theme-color"]');
  if (themeColorMeta) {
    themeColorMeta.setAttribute('content', themeColor);
  }

  const statusBarMeta = document.querySelector('meta[name="apple-mobile-web-app-status-bar-style"]');
  if (statusBarMeta) {
    statusBarMeta.setAttribute('content', statusBarStyle);
  }
}

这个方法在 Android 和桌面浏览器上表现完美，但在 iOS PWA 中——毫无反应。状态栏纹丝不动。

踩坑——试图删除并重建 Meta 标签

当直接修改 content 属性无效后，我尝试了更激进的做法：删除旧的 meta 标签，然后创建一个新的。理论是 iOS 可能会重新读取新插入的 meta 标签。

// 删除现有的 meta 标签
const oldStatusBar = document.querySelector('meta[name="apple-mobile-web-app-status-bar-style"]');
if (oldStatusBar) {
  oldStatusBar.remove();
}

// 创建一个新的
const newStatusBar = document.createElement('meta');
newStatusBar.setAttribute('name', 'apple-mobile-web-app-status-bar-style');
newStatusBar.setAttribute('content', 'black');
document.head.appendChild(newStatusBar);

结果呢？不仅对 iOS 完全无效，还引入了一个新的 bug：

Uncaught TypeError: Cannot read properties of null (reading 'removeChild')

根本原因是，删除初始 HTML 结构中存在的 DOM 节点与 React 的 hydration 机制产生了冲突。当 React 后续尝试协调 DOM 时，发现那些节点已经不存在了。

经验教训：在 React 应用中，避免删除初始 HTML 结构中存在的 DOM 节点。如果必须操作 meta 标签，应该修改属性而不是删除节点。

真正的解决方案——black-translucent 沉浸式模式

既然 iOS 不支持运行期动态切换状态栏样式，解决方案就是放弃切换，改用一种在两种主题下都好看的样式。

这就是 black-translucent：

<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">

它让状态栏变成透明的，并允许页面内容延伸到状态栏下方。这是在 iOS Safari PWA 模式下最接近「原生应用」体验的方式。

核心优势：因为状态栏是透明的，透过它看到的内容会自动适配当前主题——深色背景透出深色内容，浅色背景透出浅色内容。完全不需要切换 meta 标签。

如何让它生效——安全区域适配

使用 black-translucent 并非即插即用。需要处理一个关键细节：安全区域。

当状态栏变成透明后，你的内容会流到它下面。如果不做适配，导航栏和页面内容会被状态栏部分遮挡。

第一步：配置 viewport-fit=cover

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

viewport-fit=cover 告诉 iOS 让视口延伸到安全区域（状态栏、刘海、底部指示条等）。没有这个设置，env(safe-area-inset-*) CSS 变量的值永远是 0。

第二步：调整 Header

对于固定在顶部的 Header，需要将安全区域边距添加到其高度和内边距中：

<header className="fixed top-0 left-0 right-0 z-40">
  <div
    className="flex items-center justify-between"
    style={{
      height: 'calc(64px + env(safe-area-inset-top))',
      paddingTop: 'env(safe-area-inset-top)',
    }}
  >
    {/* header 内容 */}
  </div>
</header>

height: calc(64px + env(safe-area-inset-top)) 确保总高度包含状态栏区域，而 paddingTop: env(safe-area-inset-top) 将内容下推，使其位于状态栏下方。

第三步：调整主内容区域内边距

主内容区域需要适配增大的 Header 高度：

<main style={{ paddingTop: 'calc(64px + env(safe-area-inset-top))' }}>
  {/* 页面内容 */}
</main>

这确保内容始终从 Header 下方开始，即使安全区域边距非零。

为什么这个方案对所有设备都有效

env(safe-area-inset-*) CSS 变量具有优雅降级特性：

在没有安全区域的设备（大多数桌面端、老款手机）上，值为 0，因此布局行为与使用固定 64px 高度完全一致。

总结

核心经验：当遇到无法改变的平台限制时（比如 iOS 的 meta 标签行为），通过选择不需要该功能的方案来绕过它。black-translucent 把一个限制变成了优势——一个透明状态栏，自动适配任何主题。