shopify-alt-text

Shopify Alt Text

为 Shopify 商店中的图片补齐缺失的替代文本。替代文本首先是无障碍访问要求（屏幕阅读器会朗读它），其次才是图片 SEO 信号。此技能为没有替代文本的图片补齐内容；不会改写已有的替代文本。

用于补齐 SEO 标题和描述的姊妹技能是 shopify-seo-metadata：安全模式原则相同，处理的字段不同。在你开始批量处理之前，FIND 阶段（统计整个商品目录中有多少图片缺少替代文本）属于 shopify-catalog-audit。

一次写入，两种查找路径

图片位于 Shopify 商店中的两个地方，但两者都通过同一个 mutation写入。商品图片和 Files 库中的图片都是 MediaImage 节点，而 MediaImage 是 File 子类型，因此只需一个 fileUpdate 就能为任一图片设置 alt。无需另外学习产品媒体替代文本 mutation。

• fileUpdate 是唯一的写入方式。它接收图片的 MediaImage GID 和新的 alt。两个源工具都会汇入这条写入路径。（Shopify 的旧版 productUpdateMedia 已在 shopify.dev 上标记为弃用；不要用它设置替代文本。）
• 查找图片有两种方式，修复方式只有一种：
  • *产品媒体：*分页读取商品，并读取每个商品 product.media 下的 MediaImage。需要 read_products。
  • *Files 库：*对 files 连接分页读取（内容 → Files：主题分区、元对象、富文本、系列横幅）。需要 read_files。
  • 两种方式都会提供 MediaImage GID；将其直接传给 fileUpdate。

两种查找路径的完整计数、获取、更新和验证操作示例见 references/queries.md。

商店访问

每项会访问 Admin API 的技能都会以这段说明开头。有两种方式；任选其一。

**方式 A，自定义应用令牌（可编写脚本）。**在 Shopify 管理后台中：设置 → 应用和销售渠道 → 开发应用 → 创建应用 → 授予下方所需的最小权限，然后安装应用并复制 Admin API 访问令牌。导出令牌；切勿将其写入已提交的文件：

export SHOPIFY_STORE="your-store.myshopify.com"
export SHOPIFY_ACCESS_TOKEN="<your Admin API access token>"   # keep it in the env, not on disk

调用 GraphQL 端点（此技能所需的最小权限：read_products 用于枚举商品图片所属商品，read_files 用于分页读取 Files 库，write_files 用于通过 fileUpdate 为两处图片设置替代文本）：

curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ shop { name } }"}'

**方式 B，Shopify CLI OAuth（不存储令牌）。**运行 shopify store auth --store $SHOPIFY_STORE --scopes read_products,read_files,write_files，然后运行 shopify store execute 执行已验证的操作。适用于无需令牌、由所有者交互式登录的商店。

**工具包预检。**方式 B 依赖 Shopify CLI：先运行 shopify version，如果未安装则安装。若要使用完整的 Admin GraphQL 架构和已验证的执行方式，请将此技能与 Shopify 官方 AI toolkit 插件配合使用。在 Claude Code 中，检查 claude plugin list；如果未安装：

claude plugin marketplace add Shopify/Shopify-AI-Toolkit
claude plugin install shopify-plugin@shopify-ai-toolkit

建议使用，但并非必需：方式 A 只需要 curl 和令牌。工具包为 Agent 提供 API；此技能为其提供操作指南。

操作示例，而非脚本

这是**操作示例，而非程序。**参考文档中的 GraphQL 代码块是可复制并改编的起点：针对当前架构，为每次任务编写临时代码，运行后将其丢弃。不要发布长期使用的二进制文件，否则 Shopify 更改架构后，它会在无人察觉的情况下逐渐失效。

安全模式／预览／验证准则

将此准则作为独立规则，并且每次都执行。这是在实时存储中批量写入；严格遵守规范，才能避免一场干净利落的批量处理变成支持工单。

1. 仅填补缺失内容，绝不覆盖。 只有当图片的 alt 经去除空白字符后为 null 或空值时，才将其视为候选图片。已有 alt 文本的图片，即使写得不理想，也不在处理范围内。覆盖现有 alt 是需要由人工针对每张图片单独做出的决定，绝不是批量处理的默认行为。
2. 先预览只读计数。 在进行任何修改前，针对即将处理的查找路径运行计数查询，并查看返回的数字。进行合理性检查：一家有 300 件商品的商店，“1,900 张商品图片缺少 alt”是合理的；同一家商店若显示“40,000 张缺少 alt”，就说明筛选条件有误（很可能把非图片文件或已有说明文字的图片也计算在内）。如果计数远超预期，请停止并重新确定范围，不要继续。
3. 用实际的 1-token 补全预检生成 API 密钥。 如果你使用大模型为图片添加说明，请在批量运行前发送一次真实的（低成本、1-token）补全请求，并确认返回 200。不要依赖 models.list／仅验证身份的检查：能够列出模型的密钥，实际补全请求仍可能失败（例如账单、特定模型访问权限或组织限制问题），这样你会在批量处理了 400 张图片后才发现，而不是提前发现。
4. 记录每次写入，然后通过 Admin API 验证。 为每次写入保留日志（图片 GID、查找路径、旧 alt、新 alt、状态），以便审计并撤销有问题的批次。写入后，通过 admin/api/.../graphql.json 重新查询相同图片，并确认 alt 已填充。店面使用 CDN 缓存，几分钟内显示的仍可能是过时的（空）alt；这不能证明写入已生效。参考文档中提供了回读查询。
5. 绝不打印或提交 Admin API 访问令牌或生成密钥。 两者都应从环境变量中读取。

优质 alt 文本的标准

alt 文本应为无法看到图片的人描述图片。它不是堆砌关键词或重复商品宣传语的地方。

• 描述图片，而非营销内容。 使用“棕色皮革周末旅行包，配黄铜拉链，侧视图”，而不是“高端手工包，免费送货，立即选购”。
• 控制在约 125 个字符以内。 屏幕阅读器会读出整段字符串；过长的 alt 听起来很费劲。大多数屏幕阅读器指南都将约 125 个字符视为实用上限。写入前，将生成的说明限制在 125 个字符以内。
• 不要堆砌关键词。 重复商品标题再加上一串搜索词，既损害其原本旨在支持的无障碍体验，也会被搜索引擎视为垃圾信息。用一句自然的描述即可。
• 跳过装饰性和重复图片。 纯背景纹理或占位图片应使用空 alt（alt=""），而不是添加说明。如果某件商品的五张图片只是角度近似，就不必为每张图片各写一段不同的说明；只有在视力正常的用户能注意到区别时才加以区分（“正面”“背面”“模特上身”）。
• 不要使用“图片为”／“照片为”之类的前缀。 屏幕阅读器已经会提示这是图片；此类前缀只是多余的干扰。如果生成器添加了这类前缀，请将其删去。

即使你通过图片（视觉模型）生成说明，仍须按照上述安全模式规则检查每一次写入。权威指南：W3C WAI 的 alt 文本决策树。

参考资料

• references/queries.md：两种查找路径（商品媒体和 Files 库）的计数／获取／更新／验证方案；所有写入均通过 fileUpdate 完成，并包含分页和 MIME 筛选。

来源与维护

最后验证时间：2026-07-05。GraphQL 固定使用 Admin API 2025-07；Shopify 按季度滚动弃用版本，因此在信任特定版本的说法前，请通过 shopify.dev 确认 fileUpdate。productUpdateMedia 已弃用；fileUpdate 是当前用于为商品媒体和 Files 写入替代文本的方式。任何人都可以运行只读复核，列出商品媒体并查看哪些缺少替代文本，同时不做任何修改：

curl -s "https://$SHOPIFY_STORE/admin/api/2025-07/graphql.json" \
  -H "X-Shopify-Access-Token: $SHOPIFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ products(first: 5) { edges { node { title media(first: 10) { edges { node { ... on MediaImage { id alt } } } } } } } }"}'

权威文档： fileUpdate 和 WAI 图片教程。这些技能总结了文档未涵盖的实操经验；不能替代参考文档。