
apple-touch-icon 的 <link> 标签必须写在 里
浏览器只在解析 阶段读取这个标签,放错位置(比如塞进 或 JS 动态插入)就完全无效。iOS Safari 和主屏幕添加逻辑不支持运行时发现图标。
- 必须用
<link rel="apple-touch-icon" href="/icon-180.png">,不能省略rel或写成apple-touch-icon-precomposed(已废弃) -
href值必须是绝对路径或根相对路径(如/icons/icon-180.png),协议相对路径(//example.com/icon.png)在某些 iOS 版本会失败 - 不要指望
<meta name="apple-mobile-web-app-capable">能替代图标声明——它只控制全屏模式,和图标无关
尺寸和格式:180×180 PNG 是唯一可靠选择
iOS 主屏幕图标实际渲染时会做裁剪、圆角、阴影和高斯模糊,但前提是原始图足够清晰、无透明边框、纯色背景。用小尺寸(如 57×57)或 ICO 格式会导致模糊、拉伸或直接 fallback 到网页截图。
- 只提供
180×180一种尺寸即可覆盖 iPhone SE(2nd)到 iPhone 15 Pro 所有机型;多尺寸<link>标签对主屏幕图标无实际增益,反而增加 HTML 体积 - 必须用 PNG,带 alpha 通道的 PNG 在 iOS 上会被自动填充为黑色背景(不是透明),所以设计时就要用纯白/深灰底色 + 图标居中
- 避免使用 WebP 或 SVG:
apple-touch-icon不支持这些格式,Safari 会静默忽略
常见错误:404、缓存导致图标不更新
图标链接返回 404 时,iOS 不报错也不提示,而是直接显示网页缩略图;更麻烦的是,一旦图标被缓存,换新图后用户不手动删主屏幕快捷方式,旧图会一直显示。
- 上线前务必用 Safari 真机访问
https://yoursite.com/icon-180.png直接测试路径是否可访问、响应码是否为 200 - 更新图标后,在
<link>的href中加入版本参数,例如/icon-180.png?v=2,避免 CDN 或系统级缓存干扰 - 不要依赖
apple-touch-icon-precomposed来跳过效果处理——这个属性在 iOS 7+ 已被忽略,加了也没用
调试方法:用 Safari 开发者工具看是否加载成功
真机上无法直接查图标加载日志,但桌面 Safari 连接 iOS 设备后,可在「资源」面板里搜索 apple-touch-icon,确认请求发出且返回 200。
立即学习“前端免费学习笔记(深入)”;
- 在 macOS Safari 的「开发」菜单中启用「iPhone/iPad」选项,用 USB 连接设备,打开网页后再检查 Network → All Resources
- 如果看到
apple-touch-icon.png请求状态是 404 或 pending,说明路径或服务器配置有问题 - 注意:模拟器不触发图标下载逻辑,必须用真实 iOS 设备测试添加主屏幕流程











