变体只有一张图，商品有二十张：按选中变体过滤商品图库
一位用 Horizon 主题的商家问了一个 Shopify 店主问了十年的问题：顾客选黑色，就只该看到黑色的图——不用任何付费 app。24 小时内，这个帖子集齐了这个问题所有经典的错误答案：把布局设置当过滤、把「每色一张主图」当「每色一整套图」、伸手要店铺 URL 的服务推销，以及一份 OP 没能跑起来的可用代码。这篇文章就是那个帖子没等到的答案。
TL;DR：「只显示选中变体的图片」是两个戴着同一个名字的不同问题。案例 A——每个颜色一张代表图——原生免费、任何套餐都行：在商品后台给每个变体指定主图，Horizon 用户再到媒体图库块设置里打开**「选择变体后隐藏其他变体的媒体」**（田野报告，659928 帖三位独立发帖人互证；它只隐藏到「每变体一张指定图」的粒度）。案例 B——每个颜色一整套图——没有任何原生支持：Liquid 里的 product.media 是所有变体共享的一个扁平池子，Horizon 没有任何设置能改变这一点。案例 B 的免费、非 Plus、无 app 路线是 alt 文本标记 + Custom Liquid/JS 过滤；Plus 店用官方 Combined Listings 零代码解决。网格还是轮播是布局选择，从来不是过滤器。
这是我们的 Shopify 主题实战避坑系列第 1 篇。选题证据是一个真实的 Shopify 社区帖子（主题 659928，全文按田野报告标注）：24 小时 13 帖，OP 两次追问，没有采纳答案。
问题
2026 年 8 月 2 日，一位商家在 Shopify 官方社区发了一个被问了十年的问题（帖子 659928，Shopify Discussion 版）：
我用 Horizon 主题。顾客选黑色，就只该看到黑色的图；选白色，就只该看到白色的图。我不想用任何付费 app，有没有免费的代码或方案？
24 小时内，这个帖子集齐了这个问题所有经典的错误答案：
- 设置诱饵。第一个回复指向媒体图库块的布局设置——网格还是轮播。布局不是过滤：两种布局都会把所有图片全列出来。
- 一张图的误会。两位回答者描述了在后台给变体指定图片的操作，然后断言「这样就能实现」。确实能——但只到「每个颜色一张主图」为止。商家真正问的是每个颜色一整套图。
- 服务推销。「把你的店铺 URL 发我，我看看你的主题」——这不是答案，是揽活。
- 能跑但脆弱的代码。一位开发者贴出了实测过的 alt 文本 + Custom Liquid 方案，附前后对比截图。OP 照着做了，回报：「我没能让它跑起来。」
帖子最终没有采纳答案，OP 依然没有过滤后的图库。还有发帖人贴出另一个 Horizon 并行帖（v4.1.3，不同店铺，同样症状）——这是群体性困惑，不是某个商家倒霉。
根因
混乱的根源在于：Shopify 的数据模型给了你两个看起来很像、实际上完全不同的东西：
- 变体可以携带自己的媒体——在 Liquid 里是
variant.featured_image/variant.featured_media，在 Admin GraphQL API 里是ProductVariant.media。你在商品后台点开某个变体、给它指定图片时，设置的就是它。每个变体只有一张「主图」，主题（包括 Horizon）会在顾客选中该变体时把它换到主图位置。这是原生的、免费的、任何套餐都能用。 - 商品的媒体集——Liquid 里的
product.media——是一个被所有变体共享的扁平池子。任何没有指定给某个变体的图片，同时属于所有颜色。数据模型里根本不存在「这五张图属于黑色」这种结构。
所以「只显示选中变体的图片」要拆成两个完全不同的问题：
| 案例 | 你想要的 | 原生支持 |
|---|---|---|
| A | 每个颜色一张代表图，选中时切换 | 有——变体主图，所有主题都行 |
| B | 每个颜色一整套图（3-8 张），选中时过滤 | 没有——数据模型不支持，Horizon 也没有这个设置 |
下文全部围绕案例 B。如果你是案例 A，可以停在这里了：在 商品 → 你的商品 → 变体 里给每个变体指定主图；Horizon 用户再到媒体图库块设置里打开**「选择变体后隐藏其他变体的媒体」**即可。（实地报告：659928 帖中三位独立发帖人互证，#10 附截图；注意它只隐藏到「每变体一张指定图」的粒度，管不了多张图。）
最小复现
在开发店上五分钟就能复现这个问题：
- 建商品「Test Tee」，选项 颜色：值
Black、White。 - 传 6 张图：3 张黑色、3 张白色。把第一张黑图设为 Black 变体主图，第一张白图设为 White 变体主图。
- 用 Horizon 发布，商品模板，媒体图库用网格模式（Horizon 默认）。
- 前台选 Black：主图切换成黑色图——但其余 5 张（包括全部 3 张白图）依然列在图库里。选 White，反过来同样。
这就是原生行为的天花板。没有任何开关能改变它。
方案
三条路，按「非 Plus、拒绝 app」的商店优先级排序。
路线 1 — Alt 文本标记 + 图库过滤（免费、代码、无 app）
给每张颜色图填 Alt 文本（商品 → 点开图片 → Alt 文本 → 填 Black、White……；尺码表这类共用图留空）。然后按当前选中选项值过滤图库。Liquid 部分，放在商品模板的 Custom Liquid 块里：
{% assign current_variant = product.selected_or_first_available_variant %}
{% assign selected_color = current_variant.options.first %}
{% for media in product.media %}
{% if media.media_type == 'image' %}
{% if media.alt == blank or media.alt == selected_color %}
<img
src="{{ media | image_url: width: 800 }}"
alt="{{ media.alt | escape }}"
loading="lazy">
{% endif %}
{% endif %}
{% endfor %}决定这套方案在生产环境成败的细节：
product.media配合where: 'media_type', 'image'过滤是官方文档里的写法；media.alt就是你在后台填的那段 alt 文本。两者都有官方文档依据。- Alt 文本必须和选项值完全一致——
Black≠black≠Black（尾部空格）。加上浏览器缓存，这就是 659928 的 OP「代码跑不起来」的头号原因。 - 上面的代码只过滤首次渲染。前台切换颜色是浏览器端事件——你还需要一小段 JS 监听变体选择器，在不刷新页面的情况下重新过滤（或隐藏/显示）图库项。这是大多数人复制粘贴时漏掉的另一半。
- 没填 alt 的图对所有颜色保持可见——这正是尺码表、场景图想要的行为。
- 该方案在原帖中有实店 Horizon 网格布局的实测记录和前后截图：未标记的尺码表在所有颜色下正确保持可见。
路线 2 — Shopify Combined Listings（免费、官方、仅限 Plus）
如果每个颜色确实值得一整套独立媒体——以及独立 URL（投广告、做 SEO 都要用）——官方答案是 Shopify Combined Listings：每个颜色是独立商品、各有图库，组合 listing 把所有子商品展示在同一个商品页上。零代码。硬门槛：Combined Listings 仅对 Shopify Plus 套餐开放（shopify.dev 官方文档，2026-08-05 核验）。对明确排除了 app 和 Plus 的 OP 来说此路不通——但对 Plus 店这是正确答案，写任何 Liquid 之前都该先知道它存在。
路线 3 — App
存在、能用、不在范围：OP 的约束是「不要付费 app」，路线 1-2 已完整覆盖免费空间。
决策树
每个颜色只有一张图？ → 变体主图（+ Horizon「隐藏其他变体媒体」开关）。完事。
每个颜色有多张图？
├─ 是 Plus？ → Combined Listings。零代码。
└─ 不是 Plus？ → Alt 文本标记 + Custom Liquid/JS 过滤。
alt 文本与选项名逐字符对齐。检查清单
- 先判定案例：每色一张图（原生）还是每色一整套图（代码或 Plus）。
- 案例 A：后台给每个变体指定主图；Horizon 用户打开媒体图库块的「隐藏其他变体媒体」。
- 案例 B 路线 1：每张颜色图的 Alt 文本填与选项值完全一致的颜色名（大小写、拼写、尾部空格）。
- 用
media_type == 'image'和media.alt == selected_color过滤product.media；media.alt为空的保持可见，留给共用图。 - 补上变体切换的 JS 监听——纯服务端 Liquid 只能过滤首屏。
- 网格和轮播都测一遍；布局设置改的是标记结构，不是过滤逻辑。
- 下结论「代码不工作」之前先强刷/无痕——缓存的旧 HTML 是头号假阴性。
- 是 Plus？上面全部跳过：Combined Listings 原生给每个颜色独立商品和图库。
- 网格 vs 轮播是布局选择，从来不是过滤器——别让任何人把设置导览卖给你当解决方案。
Agent 能接的那段活
选哪条路线是一次性决策。持续的活在它周围：新图上传时保持 alt 文本标记同步，发现没指定主图的变体，每次主题更新后重测图库，在顾客之前抓住「改了选项名之后突然不工作」这类回退。这是一个定期的店铺卫生循环——正是店铺运营 Agent 能接管的活：检查、对照规则、把异常连同证据一起交给人。我们做开箱即用的 Agent 来接这类循环，如果你的周末也耗在这种事上，可以看看。
上文已对照 Shopify 官方文档（Liquid variant.featured_image/featured_media、media.alt 与 product.media where 过滤写法、Admin GraphQL ProductVariant.media、Combined Listings 的可用性与行为）核验，核验时间 2026 年 8 月。社区帖内容（Horizon「隐藏其他变体媒体」设置、实测过的 alt 文本方案、OP 落地失败、并行 Horizon 帖）为 Shopify 社区主题 659928 的田野报告，出现处均已标注。