manifest.json是PWA“添加到主屏幕”的硬性门槛，非可选；虽不强制放根目录，但浏览器默认只请求/manifest.json，路径错则404并静默放弃；须HTTPS（localhost除外）、Content-Type为application/manifest+json、含有效name/short_name/icons/start_url等字段。
manifest.json 文件不是“可配可不配”的附加项，而是浏览器判断能否触发“添加到主屏幕”的硬性门槛。没它，Chrome、Edge 会直接跳过安装逻辑；有它但配错，控制台报 Invalid manifest 或静默失败——这比没写还难排查。
manifest.json 必须放在网站根目录吗？
不是必须，但绝大多数情况必须。浏览器默认只请求 /manifest.json，哪怕你把文件放进了 /static/manifest.json，也得在 HTML 中显式写对路径：
<link rel="manifest" href="/static/manifest.json">
否则 404 后浏览器不会报错，只会放弃 PWA 流程。本地开发用 http://localhost 可行，但 file:// 协议下完全无效。
- 服务器返回的
Content-Type必须是application/manifest+json；Nginx/Apache 需手动配置，Vercel/Netlify 默认支持 - 路径写错时，开发者工具 Application → Manifest 面板会显示 “Manifest not found” 或空白，而非错误提示
- 改完文件后，要清空浏览器缓存（或硬刷新），否则可能加载旧版本导致验证失败
name 和 short_name 字符数与兼容性陷阱
short_name 是 Android 主屏图标下方显示的文字，Chrome 强制要求 ≤12 个字符（含空格），超长会被截断甚至拒装；name 虽无硬性上限，但建议 ≤30 字符，否则安装横幅显示不全。
立即学习“前端免费学习笔记（深入）”；
-
short_name写成"飞书文档 - 企业版"→ 触发截断或解析失败 - 混入零宽空格、emoji 或全角标点 → 控制台报
The provided manifest is empty or malformed - 两者完全一致（如都填
"飞书文档"）在部分 Android 版本上会导致图标文字重叠 - 中文场景下推荐二者一致且≤12字；英文常用
"name": "GitHub Enterprise"+"short_name": "GitHub"
icons 数组里哪些尺寸真正起作用？
Android Chrome 只认 192x192 和 512x512 这两个尺寸：缺任意一个，就不会弹出“添加到主屏幕”提示；iOS Safari 则完全忽略 icons 数组，只读 <link rel="apple-touch-icon"> 标签。
-
sizes字段必须严格写成"192x192"，不能是"192"、"192px"或"192x192px" -
src推荐用绝对路径（如"/icons/icon-192.png"），相对路径容易因页面 URL 深度不同而 404 - 所有图标必须是 PNG 格式（iOS 要求 PNG，Android 不支持 SVG 图标用于主屏）
- 512×512 图标还用于启动画面（splash screen），若缺失，某些设备会 fallback 到白屏
display 和 theme_color 的实际影响
display: "standalone" 是最常用值，让应用启动时隐藏地址栏和导航控件，视觉上接近原生 App；但若页面未适配移动端视口或存在横向滚动，用户会卡在异常 UI 中。
-
theme_color控制状态栏和地址栏颜色，必须和页面中<meta name="theme-color">值一致，否则安装后状态栏变色不生效 -
background_color仅用于启动画面（splash screen）背景，应与首页<body>背景色一致，避免闪白 -
start_url必须可访问且返回 200，若指向/index.html但该路径被重定向或返回 404，PWA 安装会失败 -
scope字段虽非必需，但一旦设置（如"scope": "/app/"），所有 PWA 页面必须在此路径下，否则导航会退出 standalone 模式
最容易被忽略的是：改了 manifest.json 后，旧版本仍可能被浏览器缓存数小时；真机测试前务必在 Application 面板里点击 Manifest 右侧的 “Update on reload”，再硬刷新页面。否则你看到的永远是上一版配置。
