shopify-redirect-mapping

Shopify 重定向映射

使用按类型区分的模糊匹配，将一组返回 404 的 URL 转换为 Shopify 商店中的有效 301 重定向，并将剩余项放入人工审核队列。此任务旨在挽回搜索权益并留住流失的访客，而不是构建完美的一对一映射。如果要通过电子表格批量应用，而非使用 API，请将最终映射交给同级 shopify-matrixify 技能中的 Redirects 工作表。

最重要的一条规则：覆盖率优先于精准度

错误但相关的重定向胜过 404。访客如果进入相近的产品页面或正确的分类页面，仍有机会转化；如果遇到失效页面，就会离开。301 指向主题相关的页面时，Google 会保留旧页面的一部分权益；URL 返回 404 时则一点也不会保留。因此，应以覆盖率为目标，而不是追求完美匹配，并让人工审核环节找出误匹配。

案例分析（某汽车生活方式品牌，已匿名处理）。 首轮对所有 URL 类型统一使用保守的 0.92 相似度阈值。在 1,010 个失效 URL 中，只生成了 6 个重定向：几乎毫无作用，商家称其毫无用处。使用按类型设置的阈值和跨类型回退重新运行后，同一份导出数据产生了 725 个有效重定向（覆盖率约为 72%）。教训很直接：不要发布保守的首轮结果。优先追求精准度的阈值看似安全，实际却毫无成效。

按类型设置阈值（默认值，不是建议值）

不同类型的 URL 对匹配宽松程度的容忍度不同。根据前缀对每个失效路径进行分类，然后仅在这些阈值范围内与同类型的有效库存进行匹配：

• 产品：0.85。 接受一些“后缀相同、产品不同”的匹配（已停产的 -jacket 页面跳转到另一款 -jacket 产品）。这是为覆盖率付出的可接受代价；审核环节会剔除确实错误的匹配。
• 集合：0.70。 大多数失效的集合 URL 都是结构调整造成的。任何相近的集合页面都比首页更适合作为落地页。
• 博客／页面：0.85。 品牌页面匹配到集合页面时使用 0.70。审核队列会处理其余情况。

跨类型回退顺序

当路径无法达到自身类型的阈值时，应向下回退到另一种类型，而不是直接放弃：

• 产品路径： 产品匹配 @0.85 → 模糊匹配集合 @0.70 → 审核队列。分类页面比首页更适合作为落地页；错误的产品比没有产品更糟，因此较弱的产品匹配应回退到集合匹配，而不是强行采用。
• 集合路径： 集合匹配 @0.70 → 审核队列。

绝不要悄悄回退到 /（首页）。 回退到首页看似实现了 100% 的覆盖率，却会抹去唯一能提示某个 URL 仍需人工关注的信号，还会让重定向的主题相关价值荡然无存。无法匹配的路径应进入审核队列，而不是跳转到首页。

阈值无法解决的问题

某些规格差异对算法而言与字符串完全相同：12mm 配件的路径 slug 与 14mm 配件的路径 slug 只差一个字符，S 码变体与 XL 码变体几乎完全一样。模糊匹配会自信地选错。这些条目应在审核时手动从自动应用集合中剔除。人工判断无可避免，也没有任何阈值能消除这一问题。

三类输出

每个匹配路径都恰好归入一类。这种划分让审核过程可审计，也能明确审核范围：

1. 自动应用：达到其类型阈值。推送前仍需快速检查，但默认应予以发布。
2. 审核：低置信度匹配、媒体资源（.jpg、.mp4、/assets/）、格式错误的行，以及所有进入审核队列的条目。由人工在此设置或确认目标。
3. 跳过：无需操作，即最佳目标与源路径相同。对源路径去重，确保一个失效 URL 只生成一个重定向。

审核轮次预算

要做好迭代准备。上面的匿名案例经过了多轮处理（6 → 725 条重定向），随着添加回退阶段并逐步清理审核队列，结果不断完善。 首次合作至少预留 2–3 轮：运行、检查各类别、调整阈值或手动编辑目标，然后重新运行。只生成一次性重定向映射，说明你只优化了准确率，遗漏了覆盖范围。

存储访问权限

此技能通过 Admin API 读取库存并写入重定向。选择一种方式；切勿将令牌写入已提交的文件。

方式 A，自定义应用令牌。 在 Shopify 管理后台中：Settings → Apps and sales channels → Develop apps → 创建应用 → 授予此技能所需的最小权限范围 （read_products、read_content、read_online_store_navigation、 write_online_store_navigation），安装应用，然后复制 Admin API 访问令牌。将其保存在环境变量中：

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

方式 B，Shopify CLI OAuth（不存储令牌）。 执行 shopify store auth --store $SHOPIFY_STORE --scopes read_products,read_content,read_online_store_navigation,write_online_store_navigation ，然后执行 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；此技能则提供操作指南。

修改前先预览；保持非破坏性

• 先读后写。 先获取实时库存和现有重定向列表。创建重定向前，先查询现有列表并跳过重复项：如果源路径已存在重定向，urlRedirectCreate 就会报错。
• 先备份。 大批量写入前，导出商店当前的重定向（使用 Matrixify 导出或导出 urlRedirects），以便还原本轮操作。
• 通过 Admin API 验证，而非查看店面。 店面会受到 CDN 缓存影响，无法准确反映最新状态。通过 API 重新查询重定向，确认每项写入；然后用 curl -I 抽查几个旧路径，确认返回 301，且 location 指向映射后的地址。

操作方案，而非脚本

references/pipeline.md 中的 GraphQL 和匹配逻辑是可复制并按需调整的起点。Agent 会针对每次合作，依据当前架构编写临时代码、运行后丢弃：这样能适应 Shopify 每季度的架构变更，避免发布后悄然过时的二进制文件。八步操作手册、匹配算法规范、urlRedirectCreate 和 Matrixify 应用方案、重定向到 404 的失效扫描（urlRedirectUpdate），以及 WordPress URL 转换都在该文件中。

参考资料

• references/pipeline.md：八步操作手册，涵盖从 GSC 404 导出 → 获取库存 → 匹配算法规范 → 应用 → 重定向到 404 的失效扫描 → 使用 curl -I 验证，以及 WordPress 模式转换。

来源与维护

上次验证：2026-07-05。GraphQL 固定使用 Admin API 2025-07 版本；Shopify 按滚动的季度计划弃用版本，因此在信任特定版本的说法前，请先通过 shopify.dev 核对变更和查询名称。任何人都可以运行的只读复验：

# 1. List existing redirects (confirms scope + shows current map)
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":"{ urlRedirects(first:10){ edges{ node{ path target } } } }"}'

# 2. Probe an old path and confirm it 301s where you expect
curl -sI "https://$SHOPIFY_STORE/old-path" | grep -iE "^(HTTP|location)"

权威文档：Shopify 的 URL redirects 和 Admin GraphQL API；从 Google Search Console （Pages → Not found）获取 404 导出。这些技能记录了文档中没有的操作经验；它们不能替代参考资料。