PWA 图标 manifest 排错：路径、实际文件与安装缓存
检查部署后的 manifest、图片响应、真实尺寸和已安装应用缓存，区分标签页 favicon 与 PWA 安装图标更新问题。
PWA 图标不更新时，先检查浏览器真正收到的 manifest 和图片 URL。更换标签页 favicon，不一定会替换已安装应用的图标，因为它们可能来自不同声明与缓存。
Favicon/PWA 生成器准备图片和起始 manifest。把输出部署进网站后，仍需让路径与实际发布的文件一致。
插图：原创生成的概念示意，不是界面截图、客户结果或平台验收记录。
区分标签页与安装图标
HTML 的 favicon 声明用于标签页，manifest 的 icons 条目描述 Web 应用图标。因此，页面可能显示新标签图，已安装的快捷方式却仍保留旧图片。
先记录问题发生在哪里：标签页、安装提示、应用启动器，还是已经安装的应用。再写下浏览器与操作系统，才能把“图标坏了”变成可复现任务。
找到页面实际引用的 manifest
检查页面的 manifest 链接，直接打开 URL。确认响应是预期 JSON，不是登录页、重定向循环或通用 HTML 回退。应看部署响应，而不只看编辑器里的文件。
当前生成器输出 Web/site.webmanifest、android-chrome-192x192.png 和 android-chrome-512x512.png。起始模板使用站点根相对路径；如果把图片部署进其他目录，就要更新引用，不能仍指向不存在的根文件。
逐个打开图片 URL
MDN 的 manifest 图标参考说明 src、sizes、type 与 purpose 的含义。相对路径以 manifest URL 为基准，而 / 开头的路径从站点根开始。
打开每张被声明的图片，核对响应。即使 URL 以 .png 结尾，错误页面也不是有效图片。能在本地打开的文件，仍可能没部署成功，或被页面的图片策略阻止。
将声明尺寸与真实图像比较。生成后又缩放了图片，就应同时更新条目。文件名包含 192 或 512，不等于它真的具有该尺寸。
只声明素材支持的用途
当前输出是普通图标流程，不生成单独经过测试的 maskable 图像。给现有条目加 purpose: "maskable"，不会自动重新设计安全区。
需要 maskable 素材时，按用途准备并检查裁切，必要时也保留普通图标。用尺寸指南核对已生成的输出，再查看目标浏览器的安装要求。
已在浏览器检查的 manifest 与图标示例
2026 年 10 月 1 日，本地 Chrome 154 打开了包含当前导出 manifest 和图标文件的原创测试站点。manifest 返回 200，类型为 application/manifest+json；相对地址 start_url 和 scope 解析为测试站点根目录。两张图标均返回 200，浏览器位图解码确认尺寸为 192 × 192 与 512 × 512 像素。favicon 和 Apple touch icon 声明也已分别检查。
在解压后的示例目录运行以下命令，然后打开 http://localhost:8892/。若将文件放入子目录，请更新从根目录开始的图标 URL。
python3 -m http.server 8892 --bind localhost本次验证了解析、响应和图像解码。未观察到安装推广事件或完成安装，standalone 显示为 false。示例不提供 maskable 图稿或 service worker，实际安装仍需单独测试。
先观察浏览器，再清空数据
打开浏览器的应用或 manifest 检查工具，观察解析后的内容、图标预览和请求错误，再看 manifest 与图片的网络响应。这样能区分路径错误和缓存响应。
对于可丢弃数据的测试安装，可在确认新资源后移除并重新安装。如果清理站点数据，要理解它可能删除应用本地数据。先做有目标的检查，而不是为排错清空真实用户的内容。
使用明确版本的图片 URL，有助于跟踪部署与缓存。更新引用并记录安装的是哪一版，不要让每次请求都生成随机地址；稳定的版本资源更容易缓存与诊断。
单独验证安装流程
MDN 的安装指南介绍更广泛的要求。有效图标只是流程的一部分，图标导出并不能让任何网站都在所有设备上安装。
使用受控测试站点、真实部署的 manifest 和目标浏览器。分别记录 manifest 加载、图片获取和安装呈现。桌面检查不能写成手机安装测试。
一次实际的 Safari 安装
2026 年 10 月 2 日，同一测试站点已通过隔离的 iPhone 17 模拟器、iOS 26.5 Safari 添加到主屏幕，并启用“作为网页 App 打开”。My App 图标使用原始 XY 图案；点击后，测试站点在独立 Web 应用中打开，没有 Safari 地址栏。这验证了该本地 Safari 流程，不代表 Chromium 安装、离线能力或真机表现。
按照 Apple 的 Safari 操作说明，打开站点，依次选择更多 → 共享 → 添加到主屏幕，保持“作为网页 App 打开”开启，再点添加。随后点击新图标，核对图案和打开地址。测试站点仍未提供 service worker 或专用 maskable 图案。
常见问题
标签页更新了，安装图标为什么没变？
核对 favicon 与 manifest 的独立声明，再检查已有安装的缓存。新 favicon 可能正确，但 manifest 仍引用另一文件。
只改文件名来匹配 manifest 可以吗？
可以对齐名称，但还要检查真实格式与尺寸。改名不等于转换或缩放。
所有浏览器会显示完全一样吗？
不会。安装界面与图标用途支持存在差异，应验证目标浏览器和设备。
完成可复现检查
确认 manifest URL，跟踪图片引用，核对实际文件，再测试全新的可丢弃安装。需要替换图片时回到 PWA 生成器。
更多文章
通讯
保持更新
将最新的应用设计技巧和图标趋势发送到您的收件箱。