如果你曾负责过定制化 Drupal 10 或 11 网站的上线，你一定对这个场景不陌生：你花了几周时间完美配置了 Twig 模板、复杂的 Views 和分类结构。然后，你满怀期待地打开 Safari 浏览器，却发现标签页上依然挂着那个顽固的 Drupal 蓝色水滴图标。

要彻底替换掉这个核心自带的默认图标，光靠把图片丢进 public 目录是远远不够的。Drupal 激进的缓存机制和复杂的主题继承树，让这个看似简单的任务变得异常令人抓狂。在这份 drupal favicon setup guide 中，我们将手把手教你如何永久替换核心图标，确保你的品牌在 2026 年的所有设备上都显得专业清晰。

看看那些大型企业团队（比如红帽公司或顶尖大学）是如何管理他们的 Drupal 平台的。他们极少依赖后台 UI 来上传关键的品牌资产。相反，他们会将现代化的 SVG 图标直接硬编码到主题层中。我们今天就要采用这种最专业的做法。

为什么不推荐使用默认的 UI 方法？

Drupal 确实提供了一个内置的方法来更改 favicon。如果你进入 外观 > 设置 > 你的主题，你会看到一个选项，可以取消勾选默认的快捷方式图标并上传自定义图标。

我强烈建议不要在生产环境中使用这种方法。

为什么？首先，它依赖于托管文件系统，这意味着你的图标 URL 会变成类似 /sites/default/files/favicon.ico 的形式。一旦你迁移数据库或丢失了 files 目录，图标就会失效。其次，这个 UI 界面通常只接受单一的传统 ICO 文件，完全无视了 2026 年主流的 SVG 和 Apple Touch Icon 现代标准。

专业的 Drupal Favicon 设置指南

为了做到万无一失，我们需要绕过 UI，将图标直接注入到主题中。在动代码之前，请先使用 Mzu favicondl 生成你的现代图标集。你需要一个清晰的 SVG 和一个作为后备的 ICO 文件。

步骤 1：将文件放入你的主题目录

不要放在公共的 files 目录，而是将图标存放在你的自定义主题内。为它们创建一个专用文件夹，以保持代码整洁并纳入版本控制。

步骤 2：覆盖 html.html.twig

Drupal 核心通过 html.html.twig 模板控制 <head> 的输出。如果你的主题还没有这个文件，请从核心系统模块（/core/modules/system/templates/html.html.twig）将它复制到你主题的 /templates/layout/ 目录中。

打开该文件。你会看到一个 <head-placeholder token=...> 标签。就在它下方，使用 Twig 的当前主题路径变量，硬编码你的现代 SVG 图标链接。

<link rel='icon' href='{{ active_theme_path() }}/icons/favicon.svg' type='image/svg+xml'>
<link rel='alternate icon' href='{{ active_theme_path() }}/icons/favicon.ico'>
<link rel='apple-touch-icon' href='{{ active_theme_path() }}/icons/apple-touch-icon.png'>

这能确保你的图标与代码库一起进行版本控制，并且永远不依赖数据库状态。

步骤 3：移除核心附加组件

即使你硬编码了 Twig 标签，Drupal 仍可能通过页面附件（page attachments）注入其默认的图标标签，导致 DOM 中出现重复标签。为了剥离它，我们在 your_theme.theme 文件中使用预处理钩子。

/**
 * Implements hook_page_attachments_alter().
 */
function your_theme_page_attachments_alter(array &$attachments) {
  foreach ($attachments['#attached']['html_head_link'] as $key => $value) {
    if (isset($value[0]['rel']) && $value[0]['rel'] === 'icon') {
      unset($attachments['#attached']['html_head_link'][$key]);
    }
  }
}

这段代码会拦截页面构建过程，强行剥离 Drupal 试图原生注入的任何图标链接，只留下你干净的 Twig 实现。

清除 Drupal 缓存

你可以修改世界上所有的代码，但在清除缓存之前，Drupal 是不会显示这些更改的。渲染缓存出了名的顽固。

  1. 打开终端并导航到你的项目根目录。
  2. 运行 drush cr（重建缓存）。
  3. 如果你使用了像 Varnish 这样的反向代理或 Cloudflare 等 CDN，请一并清除它们的缓存。

如果你仍然看到旧的蓝色水滴，很可能是你的浏览器缓存了它。请阅读我们的强制清除 Favicon 缓存指南来解决本地浏览器的顽固问题。

Drupal 10/11 中的常见陷阱

如果你的设置仍然失败，请检查以下常见原因：

别再和 Drupal UI 较劲了。通过将图标逻辑移入主题代码库，你可以确保在每个浏览器标签页中呈现稳定、受版本控制且专业的品牌形象。