Favicon 不显示、更新不生效？从生成文件到 WordPress 与 CDN 排查

生成了 favicon，浏览器却还显示旧图标，先别反复换图片。把问题拆成三层：页面实际声明了哪个图标、这个地址返回了什么文件、浏览器是否仍在使用旧缓存。按这个顺序检查，比连续清空所有缓存更容易找到原因。本文给出适用于静态站和 WordPress 的配置示例、只读检查脚本，以及多语言子目录和 CDN 场景的判断方法。

如果还没有图标文件，可以先用 Favicon Generator 准备资源。其页面提供文字、emoji、图片与 SVG 入口，并列出 SVG、ICO、PNG 和主屏幕图标输出。这里把它作为文件准备工具；下面的重点是验证文件怎样被网页引用，以及部署以后是否真正可用。工具界面的功能说明不等于本文已经对全部导出模式做过兼容性测试。

先决定要修的是哪一种图标

浏览器标签页、手机主屏幕和搜索结果都可能显示网站图标，但它们并非同一个验收目标。标签页正常，不能证明主屏幕图标正确；本机已经显示新图，也不能证明搜索引擎已经重新处理。开始排查前，写清楚出问题的设备、浏览器、页面地址和实际看到的图案，保留当前声明和文件地址，避免修改后失去对照。

对于普通内容站，先让标签页和常用手机入口工作即可。不要因为资源包里有 manifest 就顺便更改现有应用名称、启动地址或作用域；这些字段会影响安装体验，属于另一个任务。已有 PWA 的项目则需要把资源包与当前 manifest 合并检查，不能直接覆盖。

准备文件：小尺寸可读，比格式数量更重要

图标要在很小的面积里被辨认出来。复杂标志、细线和长文字缩小后可能只剩一个模糊色块。建议先使用简单轮廓或单字符，预览小尺寸下的留白和对比度；浅色背景与深色背景都检查一次。透明区域本身没有问题，但白色线条放到浅色标签栏上就可能看不见。

导出之后，检查文件的实际名称、尺寸和内容，不要只看扩展名。把 PNG 改名为 ICO 并没有完成格式转换。若项目使用 SVG，尽量保持图形自包含，避免依赖外部字体或远程图片；如果必须使用品牌字体，先在设计阶段处理字形，不要指望访客浏览器一定装有相同字体。

下面是一份静态站资源布局示例。它表示部署后可以访问的路径，并不要求每个站点必须生成同样多的文件。WordPress 的媒体附件通常放在 uploads 下，不需要为了照抄此结构而移动已有附件。

/assets/icons/
  favicon.svg
  favicon-96.png
  apple-touch-icon.png
/favicon.ico

本文示例中，PNG 备用图标按 96×96 制作，Apple Touch 图标按 180×180 制作。若你改变文件尺寸，也要同步调整声明。维护一个文件清单，记录各入口使用哪个文件；以后换品牌图标时沿着清单检查，能避免只替换其中一张图片。

页面声明：先查看输出，再修改来源

打开出现问题的页面，查看服务器返回的 HTML，并在开发者工具的 Elements 面板中检查最终的 head。前者能发现页面缓存中的旧声明，后者能看到脚本或插件追加的内容。定位所有与 icon 相关的 link，逐一记录 href、type、sizes 和 media；不要只搜索 favicon.ico，因为文件可能采用完全不同的名称。

一个普通静态页可以采用下面的写法。示例使用站点根相对路径，所以文章在不同目录层级时仍指向同一组文件。它只是配置示例，不应粘贴进文章正文后期待改变站点图标；真正的声明必须由页面模板或网站的配置入口输出到 head。

<link rel="icon" href="/favicon.ico">
<link rel="icon" type="image/png" sizes="96x96"
      href="/assets/icons/favicon-96.png">
<link rel="icon" type="image/svg+xml" sizes="any"
      href="/assets/icons/favicon.svg">
<link rel="apple-touch-icon" sizes="180x180"
      href="/assets/icons/apple-touch-icon.png">

多个 icon 声明并不自动意味着冲突。MDN 的 rel=”icon” 文档说明，浏览器会结合 media、type 与 sizes 选择适合的资源；多个候选同样合适时，顺序也会参与选择。实际需要清理的是互不知情的配置来源：主题指向旧品牌文件，插件又输出另一个版本，页面缓存还保留第三套地址。先确定每组声明的用途，再去对应设置里合并或移除。

在 WordPress 上，先检查站点图标设置、主题自己的图标选项，以及用于插入 head 代码的插件。选择一个明确的管理入口；不要一边启用自动输出，一边不断往 header 模板里追加代码。如果必须改模板，使用项目已经采用的子主题或配置机制，并先备份。直接修改父主题文件，会给下次升级留下维护问题。

子目录和 CDN：确认浏览器最终请求的地址

相对地址最容易造成“首页可以、内页不行”。例如，在没有 base 元素干预时，/en/docs/ 页面中的 href=”favicon.png” 会解析到 /en/docs/favicon.png；href=”/assets/icons/favicon-96.png” 才会从当前站点根目录定位。不要凭目录名字推测实际请求，直接在 Network 面板里查看完整 URL。

多语言站需要同时检查首页、文章页和语言目录入口。语言目录可能是独立静态页面，也可能共享 WordPress 模板，两者输出 head 的位置不同。只有某个目录失败时，优先比较页面声明与路径解析，不要立刻全站更改重写规则。对于部署在非根路径的应用，根相对地址也可能不符合发布前缀，应按项目的公开访问路径调整。

如果图标托管在对象存储或 CDN，检查公开地址是否无需登录、是否返回图像、是否重定向到签名地址，以及是否存在过期时间。不要把临时授权下载链接直接写入长期页面。HTTPS 页面也应使用可以正常访问的 HTTPS 图标地址；若页面存在内容安全策略，查看控制台中是否有相应的资源拦截记录，再按实际策略处理。

用一次 GET 分清“文件存在”和“响应正确”

能打开链接不一定意味着服务器返回了图标。某些站点会把缺失静态资源交给 WordPress 或前端路由，最终返回状态码 200 的 HTML 页面。单看状态码会误判。下面的命令对目标文件执行一次 GET，将响应头和响应体分开保存；把示例域名换成你有权检查的网站。

curl --fail --show-error --silent --location \
  --connect-timeout 5 --max-time 20 --max-redirs 5 \
  --dump-header favicon-headers.txt \
  --output favicon-response.bin \
  --write-out 'status=%{http_code}\nurl=%{url_effective}\n' \
  'https://example.com/assets/icons/favicon-96.png'
file favicon-response.bin

此处没有使用 HEAD，因为某些服务对 HEAD 与 GET 的处理不同。发生超时或 HTTP 错误时，先处理该错误，不要拿历史保存的响应体继续判断。成功后查看最终响应的 Content-Type、Cache-Control、ETag 与 Last-Modified；有重定向时，响应头文件可能包含多组头部，应以最终响应为准。PNG 常见类型为 image/png，SVG 为 image/svg+xml；若拿到 text/html，就继续检查路由、访问控制或错误页。

file 命令是辅助识别，不是完整图像解码器。服务器返回图像类型，也不能证明文件内容完整。仍需在浏览器打开该地址，确认能解码并显示正确图案。记录最终 URL 和响应体的哈希，后续复测才知道拿到的是新文件还是旧文件；不要在没有证据时把每次显示异常都归因于浏览器缓存。

只读脚本：列出页面实际声明的图标

下面的 Python 脚本只依赖标准库，请求一个页面并解析它返回的 HTML，随后列出浏览器路径解析所需的绝对地址。它不会执行 JavaScript，也不会自动下载图标；输出为后续检查提供清单，不能代替真实浏览器验收。脚本支持 base href，避免将合法的基础路径误报为错误。

from html.parser import HTMLParser
from urllib.parse import urljoin
from urllib.request import Request, urlopen
import sys

class IconParser(HTMLParser):
    def __init__(self):
        super().__init__()
        self.base = None
        self.icons = []

    def handle_starttag(self, tag, attrs):
        attrs = dict(attrs)
        if tag == "base" and self.base is None and attrs.get("href"):
            self.base = attrs["href"]
        rel = set(attrs.get("rel", "").lower().split())
        if tag == "link" and rel.intersection({
            "icon", "apple-touch-icon", "manifest"
        }):
            if attrs.get("href"):
                self.icons.append(attrs)

if len(sys.argv) != 2:
    raise SystemExit("Usage: python3 inspect_icons.py PAGE_URL")
request = Request(sys.argv[1], headers={"User-Agent": "IconAudit/1.0"})
with urlopen(request, timeout=15) as response:
    page_url = response.geturl()
    charset = response.headers.get_content_charset() or "utf-8"
    html = response.read(2_000_001)
    if len(html) > 2_000_000:
        raise SystemExit("HTML exceeds the 2 MB inspection limit")

parser = IconParser()
parser.feed(html.decode(charset, errors="replace"))
base = urljoin(page_url, parser.base) if parser.base else page_url
for icon in parser.icons:
    print(icon.get("rel"), icon.get("sizes", "-"),
          urljoin(base, icon["href"]))
if not parser.icons:
    print("No icon or manifest declaration in response HTML")

保存为 inspect_icons.py 后，用 python3 inspect_icons.py 加上页面完整地址运行。分别检查首页与一个出问题的内页，比较输出。如果原始 HTML 没有声明，而浏览器 Elements 面板里有，就检查项目是否在客户端注入。脚本默认跟随 urllib 的重定向行为，页面最终地址也会影响相对路径；碰到登录页或挑战页时，其输出不能代表正常访客页面。

更新不生效时，只处理已经定位的缓存层

先判断服务器当前提供的是什么。如果直接请求图标仍拿到旧哈希，检查部署产物、对象存储和 CDN；如果图标是新的，但页面源码依旧指向旧地址，检查页面生成和页面缓存；如果两者都正确，而某个日常浏览器仍显示旧图，再用全新隔离会话对照。这样的顺序可以减少无关操作。

WordPress 站点通常还有页面缓存插件。确认文章页或首页输出落后之后，优先清理对应 URL 的缓存，再复查源代码。不要为一个 favicon 问题停用所有插件、清空所有媒体缓存或重建数据库。CDN 同样尽量按已确认的资源地址处理，而不是直接执行全站清除。

文件名版本化可以用于明确切换部署资源，但必须同时更新引用，并考虑搜索引擎对地址稳定性的要求。临时添加查询参数适合定位问题，却不能保证所有缓存层都按参数区分；也不应该把不停变换参数当成长久方案。先查清这一层如何缓存，再决定是覆盖稳定文件、更新版本路径，还是执行一次针对性刷新。

浏览器正常以后，再单独检查搜索结果

Google Search Central 的 favicon 说明以主机名界定站点，要求首页与图标可被相应抓取系统访问，图标 URL 保持稳定；即使满足条件，也不保证一定展示。子目录不能据此获得单独的搜索结果图标。浏览器验证完成后仍需给重新抓取和处理留出时间，不能用一次本机刷新判断搜索结果已更新。

因此，/en/ 和 /jp/ 可以在各自页面上声明适合浏览器的图标，但不要把这种页面级设置当成独立搜索站点图标的保证。若根域和 www 都可访问，还应明确实际使用的主机入口，检查它的首页，而不是只测试一个自动跳转地址。更改域名跳转或 canonical 并非修复 favicon 的默认步骤，应另行评估。

完成后留下四项记录：代表页面输出了哪些声明、图标最终响应的地址与内容、隔离浏览器显示的结果、手机或搜索场景是否仍待验证。本文的配置和脚本是通用排错模板，未宣称覆盖全部浏览器版本。资料核对日期为 2026 年 11 月 6 日；下一次遇到同类问题，从已有记录比较差异，比重新下载一套图标更有效。