manifest.json 完全指南：配置、优化与常见问题实战

我的写法，亲测靠谱

做 PWA（Progressive Web App）项目时，manifest.json 是绕不开的一环。我最早以为它就是个配置文件，填几个字段就行，结果上线后发现图标不显示、横屏被禁止、安装按钮没出现……折腾了好几次才摸清门道。现在我写 manifest.json 基本固定一套模板，亲测在 iOS 和 Android 上都能正常安装、启动、显示图标，分享出来给大家参考。

先看我现在的标准写法：

{
  "name": "我的应用",
  "short_name": "App",
  "description": "一个实用的移动端工具",
  "start_url": "/?utm_source=pwa",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#000000",
  "orientation": "portrait",
  "scope": "/",
  "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"
    }
  ]
}

为什么这么写？几点经验：

• 必须包含 192×192 和 512×512 的图标：Chrome 安装 PWA 时会优先找这两个尺寸，缺了可能不显示安装提示。
• start_url 加上 utm_source=pwa 这种参数，方便后续统计来源，别小看这个，上线后才知道有多少用户是从 PWA 进来的。
• scope 设为 /，避免某些页面跳出去后无法回到 PWA 模式。
• orientation 我一般强制设为 portrait，除非是视频类应用。横屏容易导致布局错乱，而且很多用户根本不会横屏用。

这几种错误写法，别再踩坑了

我见过太多人把 manifest.json 写成“半成品”，结果 PWA 功能残废。下面这些坑我都踩过，或者帮同事修过：

1. 图标只放一个 192×192 的

你以为够了？iOS Safari 要的是 180×180（iPhone）和 152×152（iPad），Android 虽然兼容性好点，但不同厂商对图标尺寸要求不一样。我之前图省事只放 192×192，结果在三星手机上安装后图标变成白底黑框，丑得不行。后来干脆一次性生成 8 个主流尺寸，用脚本批量生成，一劳永逸。

2. start_url 写成相对路径比如 ./index.html

这种写法在本地开发没问题，但部署到子目录（比如 https://example.com/myapp/）就炸了。浏览器会解析成 https://example.com/index.html，直接 404。必须用绝对路径 / 或带域名的完整 URL（但后者不利于多环境部署）。

3. 忘记设置 background_color 和 theme_color

这两个字段控制启动时的闪屏背景和状态栏颜色。没设的话，Android 会默认用白色背景 + 黑色状态栏，如果你的 App 主色调是深色，启动瞬间会“闪白”，体验极差。我有一次上线后用户反馈“打开像卡了”，其实就是这个原因。

4. display 随便写成 fullscreen

除非你做游戏或全屏视频，否则别用 fullscreen。它会隐藏状态栏，但 iOS 上其实不支持，反而导致 Safari 地址栏不消失，PWA 感觉“没生效”。用 standalone 最稳妥，既能隐藏浏览器 UI，又兼容所有平台。

实际项目中的坑

除了配置本身，还有一些部署和调试上的细节容易翻车：

1. 文件路径大小写敏感

Linux 服务器上，/Icons/icon.png 和 /icons/icon.png 是两个文件。我有次在 Mac 上开发没问题，部署到服务器后图标 404，查了半天才发现是路径大小写问题。建议统一用小写路径，避免这种低级错误。

2. MIME 类型必须正确

服务器返回 manifest.json 时，Content-Type 必须是 application/manifest+json 或 application/json。有些老 Nginx 配置没加这个，浏览器直接忽略 manifest，PWA 安装按钮不出现。检查方法很简单：打开 DevTools 的 Network 面板，看 manifest 请求的响应头。

3. 缓存问题

改了 manifest.json 但用户看不到更新？因为浏览器会缓存它。建议给 manifest 文件加版本号，比如 <link rel="manifest" href="/manifest.json?v=1.2.3" rel="external nofollow" >，或者通过 Service Worker 控制缓存策略。不过要注意，iOS 对 manifest 的缓存特别顽固，有时候得清除 Safari 数据才能生效。

4. iOS 的“伪 PWA”

iOS 从 11.3 开始支持 PWA，但功能残缺：不能后台运行、不能推送通知、图标只能用 180×180。而且它不读 manifest.json 里的所有字段，比如 theme_color 就无效。所以如果你的用户很多是 iOS，还得额外加 Apple-specific 的 meta 标签：

<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black">
<link rel="apple-touch-icon" href="/icons/apple-touch-icon-180x180.png">

别指望一个 manifest 通吃所有平台，现实很骨感。

结尾碎碎念

说实话，manifest.json 看似简单，但细节特别多，而且不同平台行为不一致。我现在的做法是：先按 Chrome 的标准写全，再针对 iOS 补 meta 标签，最后用 Lighthouse 跑分检查是否达标。虽然有点啰嗦，但至少能保证基础体验不崩。

以上是我个人对 manifest.json 的完整踩坑总结，有更优的实现方式欢迎评论区交流。这个技巧的拓展用法还有很多（比如动态生成 manifest、多语言支持），后续会继续分享这类博客。希望对你有帮助，少走点弯路。