如何在 WordPress 导航菜单中添加图片？

导航菜单需要图标或缩略图时，可以给菜单项增加一个图片字段，再通过 WordPress 菜单过滤器输出。图片应保存为媒体附件 ID，由 wp_get_attachment_image() 生成尺寸、宽高和响应式属性。

1. 创建菜单项图片字段

使用 ACF 时，将字段组位置规则设为“菜单项等于全部”，新增图片字段 menu_image，返回格式选择“图片 ID”。

图标只是装饰时，可将替代文本留空；图片承担导航含义时，应在媒体库中提供准确替代文本。不要把菜单标题原样重复成所有图标的 alt，否则屏幕阅读器会读两遍同样内容。

2. 输出图片

nav_menu_item_title 会在链接内容生成时过滤菜单标题：

<?php
add_filter(
    'nav_menu_item_title',
    function (
        string $title,
        WP_Post $item,
        stdClass $args,
        int $depth
    ): string {
        if (
            'primary' !== $args->theme_location ||
            0 !== $depth
        ) {
            return $title;
        }

        $image_id = (int) get_field(
            'menu_image',
            $item
        );

        if ( ! $image_id ) {
            return $title;
        }

        $image = wp_get_attachment_image(
            $image_id,
            'thumbnail',
            false,
            array(
                'class'   => 'menu-item__image',
                'loading' => 'lazy',
            )
        );

        if ( ! $image ) {
            return $title;
        }

        return sprintf(
            '<span class="menu-item__media">%s</span>' .
            '<span class="menu-item__label">%s</span>',
            $image,
            esc_html( wp_strip_all_tags( $title ) )
        );
    },
    10,
    4
);

这段代码只处理 primary 菜单的顶级项目，避免后台菜单、页脚菜单和多层子菜单意外继承同一结构。

如果其他插件需要在标题中保留 HTML，不要用这段简化过滤器覆盖它们的输出；改用自定义 Walker_Nav_Menu，在一个明确的渲染层组合图片与标题。

3. 样式

.primary-menu .menu-item > a {
  display: inline-flex;
  align-items: center;
  gap: 0.5rem;
}

.menu-item__image {
  display: block;
  width: 2rem;
  height: 2rem;
  object-fit: cover;
}

移动端导航需要检查图片是否挤压文字、展开按钮是否仍有足够点击区域，以及长标题换行是否正常。

不要直接保存图片 URL

附件 ID 的优势包括：

WordPress 可以生成 srcset、尺寸和宽高属性。
替换域名、使用 CDN 或迁移站点时不需要逐项改 URL。
删除附件后能明确得到空结果。
可以使用媒体库已有的替代文本与裁剪尺寸。

导航图片属于视觉增强。即使图片加载失败，文本标签也必须仍能完成导航。