Manifest配置全解析：从基础到实战的前端必备指南

为啥要搞 Manifest 配置？

上个月接了个 PWA（Progressive Web App）需求，说是要让页面在离线时也能打开首页，还能加到手机桌面。我一听，行啊，这不就是标准的 PWA 能力嘛，核心就靠一个 manifest.json 和 Service Worker 搞定。一开始觉得挺简单，不就是配个 JSON 文件，填几个字段的事儿？结果真动手才发现，细节坑不少。

项目本身是个内容型站点，主要展示文章和图片，用户经常在地铁里看，网络不稳定。老板希望“哪怕没网也能看到上次打开的页面”，所以 PWA 的缓存能力成了刚需。Manifest 主要是用来定义应用名称、图标、启动方式这些元信息，虽然不直接管缓存，但它是让浏览器把你的网页当成“App”对待的第一步。

第一次写的 manifest.json 翻车了

我随手从 MDN 抄了个模板，改了名字和图标路径，扔到项目根目录，然后在 index.html 里加上：

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

本地跑起来看，Chrome DevTools 的 Application 面板里确实读到了 manifest，图标也显示了。我以为完事了，结果测试同事反馈：“iOS 上加到主屏幕后名字是网址，不是我们设的 app 名！”

一查才知道，Safari 对 PWA 支持有限，根本不认 manifest.json 里的 name 字段。它只认 HTML 里的 apple-mobile-web-app-title 这个 meta 标签。于是赶紧补上：

<meta name="apple-mobile-web-app-title" content="我的阅读站">

这下 iOS 正常了，但 Android 又出问题——有些低端机上图标模糊得像打了马赛克。后来发现是我只提供了一张 192×192 的 icon，而不同设备对图标尺寸要求不一样。Android 推荐至少提供 192×192 和 512×512 两种，用于不同场景（比如添加到桌面 vs 安装提示）。

图标尺寸折腾半天

我原以为随便切几张图就行，结果 Chrome 在 DevTools 里直接报 warning：“Icon size too small for optimal experience”。点开一看，建议提供 192×192 和 512×512。于是我用脚本批量生成了多套尺寸：

• 72×72
• 96×96
• 128×128
• 144×144
• 152×152
• 192×192
• 384×384
• 512×512

其实很多尺寸现在用不上，但为了兼容老设备和不同厂商（比如三星、小米的 launcher 行为不一致），还是全上了。最后 manifest.json 里 icons 数组写成这样：

{
  "name": "我的阅读站",
  "short_name": "阅读站",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#000000",
  "icons": [
    {
      "src": "/icons/icon-72x72.png",
      "sizes": "72x72",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-96x96.png",
      "sizes": "96x96",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-128x128.png",
      "sizes": "128x128",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-144x144.png",
      "sizes": "144x144",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-152x152.png",
      "sizes": "152x152",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-384x384.png",
      "sizes": "384x384",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

注意：所有图标路径必须是相对于网站根目录的绝对路径，不然在子路由页面加载时会 404。这点我一开始用相对路径，线上环境直接挂了，还好监控告警及时发现。

最大的坑：start_url 和路由冲突

我们项目用的是 Vue Router history 模式，所有路由都走前端。我把 start_url 设成 /，本地没问题。但上线后，有用户反馈：从桌面图标打开，直接跳到了 404 页面。

排查了半天，发现是 Nginx 配置问题。当用户从 PWA 启动时，浏览器会请求 start_url（即 /），但如果服务器没正确 fallback 到 index.html，就会返回 403 或 404。我们的 Nginx 之前只对已知 API 路由做了代理，静态资源走 CDN，但没处理 SPA 的 fallback。

解决办法是在 Nginx 加一行：

location / {
  try_files $uri $uri/ /index.html;
}

不过这属于部署层面的问题，和 manifest 本身无关。但如果你的 start_url 不是根路径（比如 /app），那还得确保这个路径在服务端能正确返回 HTML，否则照样白屏。

display 模式选 standalone 还是 fullscreen？

一开始我设成 fullscreen，想着沉浸式体验更好。结果测试发现，Android 上状态栏（时间、电量那些）被隐藏了，但用户没法下拉看通知，体验反而变差。而且有些系统会把 fullscreen 当成视频播放模式，自动调高亮度……太诡异了。

后来改成 standalone，保留状态栏，看起来就像个普通 App，反而更自然。除非你做的是游戏或视频类应用，否则别轻易用 fullscreen。

还有个烦人问题：主题色不生效

我设了 theme_color: "#000000"，理论上地址栏和状态栏应该变黑。但在某些 Android 机型上（尤其是国产定制 ROM），完全没反应。查了一圈，发现是厂商自己魔改了 WebView，根本不尊重这个字段。

目前没找到通用解法，只能接受“部分设备无效”的事实。好在不影响核心功能，就先放着了。不过 Safari on iOS 是支持的，至少苹果生态里能保证一致性。

最终效果还行，但不算完美

上线两周后看了下数据：PWA 安装率大概 8%，主要集中在 Android 用户。离线访问成功率 92%（剩下的 8% 是首次访问没缓存完就断网）。用户反馈“加到桌面后打开快多了”，说明体验提升是真实的。

做得好的地方：

• 图标尺寸覆盖全面，没再收到模糊投诉
• start_url 配合 Nginx fallback，启动稳定
• iOS 和 Android 基础体验对齐（靠额外 meta 标签）

还能优化的点：

• 主题色在部分安卓机失效，暂时无解
• manifest 文件没做版本控制，如果以后改名或换图标，旧用户可能缓存旧 manifest。不过影响不大，因为浏览器通常会重新 fetch
• 没动态生成 manifest（比如根据用户语言切换 name），但项目不需要，就没搞复杂

一点建议

如果你也在搞 PWA，manifest 看似简单，但细节决定成败。别只盯着 JSON 字段，一定要真机测试 iOS 和 Android 主流机型。Chrome DevTools 的 Lighthouse 能帮你检查大部分问题，但真机行为可能不同。

另外，manifest 只是 PWA 的“门面”，真正核心是 Service Worker 的缓存策略。不过那是另一个故事了……

以上是我踩坑后的总结，希望对你有帮助。如果你有更好的处理方案，比如怎么让 theme_color 在小米/华为上生效，欢迎评论区交流！