开发或定制 Shopify 商店、应用、主题与无头电商时…

适用于用户提到 Shopify、电商、在线商店、商家、GraphQL、REST、Storefront API、Admin API、商品/集合/变体/库存、订单/履约/配送、客户/账户/认证、结账/支付/配送选项、Liquid/主题/区块、应用/扩展/Webhook/OAuth、Hydrogen/React/无头/Oxygen、Shopify Functions/折扣、订阅/售卖计划、Shopify CLI、POS/零售等关键词时。

适用场景

解决思路

1. 以官方文档为依据，覆盖应用开发、主题定制、API 集成、结账扩展和电商功能，提供全面准确的 Shopify 平台指导。
2. 先准备文档：安装 `docpull`（`pipx install docpull`），再执行 `docpull https://shopify.dev/docs -o .claude/skills/shopify/docs`，将官方文档放入 `docs/shopify/`。
3. 文档可用时使用 `docs/shopify/` 下 25 个 markdown 文件，覆盖完整 API 参考、指南、最佳实践和实现模式。
4. 优先覆盖和检索领域包括：GraphQL Admin API（products、orders、customers、inventory）、Storefront API（cart、checkout、customer accounts）、REST Admin API（legacy support）、App development（authentication、webhooks、extensions）、Theme development（Liquid、sections、blocks）、Headless commerce（Hydrogen、Oxygen）、Checkout customization（UI extensions、validation）、Shopify Functions（discounts、delivery、payments）、POS extensions（in-person sales）、Subscriptions and selling plans、Metafields and custom data、Shopify Flow automation、CLI and development tools、Privacy and compliance、Performance optimization。
5. 回答问题时，先用 Grep 搜索具体主题：`grep -r 'checkout' .claude/skills/shopify/docs/ --include='*.md'`。
6. 读取具体 API 文档：`cat .claude/skills/shopify/docs/shopify/api-admin-graphql.md`、`cat .claude/skills/shopify/docs/shopify/api-storefront.md`。
7. 查找实现指南：`ls .claude/skills/shopify/docs/shopify/`。
8. 核心认证使用 OAuth 2.0：重定向到 `https://${shop}/admin/oauth/authorize?client_id=${process.env.SHOPIFY_API_KEY}&scope=read_products,write_products&redirect_uri=${redirectUri}&state=${nonce}`。
9. OAuth 2.0 用 code 交换 access token：向 `https://${shop}/admin/oauth/access_token` 发 POST，JSON body 包含 `client_id`、`client_secret`、`code`，从响应取 `access_token`。
10. 现代嵌入式应用使用 session tokens：用 `@shopify/shopify-api` 的 `shopifyApi` 初始化，配置 `apiKey`、`apiSecretKey`、`scopes`、`hostName`、`isEmbeddedApp: true`。
11. GraphQL Admin API 查询商品：使用 `products(first: 10)`，取 `edges.node` 的 `id`、`title`、`handle`、`priceRange.minVariantPrice`、`variants(first: 5)` 的 `id`、`sku`、`inventoryQuantity`。
12. GraphQL Admin API 创建商品：使用 `productCreate(input: ...)` mutation，传 `title`、`vendor`、`productType`、`variants[{price, sku}]`，并检查返回的 `userErrors`。
13. GraphQL Admin API 获取订单：使用 `orders(first: 25, query: 'fulfillment_status:unfulfilled')`，取 `id`、`name`、`createdAt`、`totalPriceSet.shopMoney`、`customer.email`、`lineItems` 的 `title` 和 `quantity`。
14. Storefront API 创建购物车：使用 `cartCreate(input: ...)` mutation，传 `lines[{merchandiseId, quantity}]`，取 `cart.id`、`checkoutUrl`、`cost.totalAmount`。
15. Storefront API 更新购物车：使用 `cartLinesUpdate(cartId: ..., lines: [{id, quantity}])`，更新后读取 `cart.id` 和 `lines` 数量。
16. 设置 Webhook：通过 API 调用 `shopify.webhooks.register`，指定 `topic: 'ORDERS_CREATE'`、`address: 'https://your-app.com/webhooks/orders-create'`、`format: 'json'`。
17. 验证 Webhook：用 `crypto.createHmac('sha256', secret).update(body, 'utf8').digest('base64')` 生成哈希，与 `x-shopify-hmac-sha256` 头比对；无效返回 401，有效解析订单并返回 200。
18. Liquid 基础：输出 `{{ product.title }}`，用 `{% if product.available %}` 条件显示 Add to Cart 或 Sold Out，用 `{% for variant in product.variants %}` 循环变体，用 `| money` 格式化价格。
19. Liquid 自定义 Section：用 `{% schema %}` 定义 `name` 和 `settings`（如 `type: product`、`id: product`、`label: Product`），在模板中用 `section.settings.product` 读取商品，并用 `img_url: '500x'` 和 `| money` 渲染。
20. Shopify Functions 折扣：导出函数，统计 `input.cart.lines` 总数量，根据数量设置折扣百分比（如 >=10 为 20%，>=5 为 10%），返回 `discounts`，通过 `orderSubtotal` 定位并设置 `percentage`。
21. Shopify Functions 配送定制：解析 `input.cart.cost.subtotalAmount.amount`，若小于 100，筛选 `input.cart.deliveryGroups[0].deliveryOptions` 中标题含 `express` 的选项，返回 `operations` 中的 `hide.deliveryOptionHandle`。
22. Hydrogen 无头电商产品页：在 `app/routes/products.$handle.tsx` 中导出 loader，用 `context.storefront.query(PRODUCT_QUERY, {variables: {handle: params.handle}})` 查询商品，用 `useLoaderData` 渲染 `title`、`featuredImage.url`、`description` 和 `AddToCartButton`。
23. Hydrogen 产品查询：定义 `PRODUCT_QUERY`，用 `product(handle: $handle)` 取 `id`、`title`、`description`、`featuredImage`、`variants(first: 10)` 的 `id`、`price.amount`、`currencyCode`。
24. Shopify CLI 常用命令：`shopify app init`、`shopify app dev`、`shopify app deploy`、`shopify app generate extension`、`shopify theme init`、`shopify theme dev --store=your-store.myshopify.com`、`shopify theme push`、`shopify theme pull`。
25. 测试商店：创建 Partner 账号 `https://partners.shopify.com`，创建 development store，安装应用，测试功能。
26. 测试数据：用 REST API 创建测试商品（`shopify.rest.Product.save`，传 `session`、`title`、`body_html`、`vendor`、`product_type`、`variants`）和测试订单（`shopify.rest.Order.save`，传 `line_items`、`customer.email`）。
27. 安全最佳实践 - API Keys：存入环境变量；绝不提交到版本控制；每个环境使用不同 key；泄露后轮换。
28. 安全最佳实践 - Webhooks：始终验证 HMAC 签名；仅使用 HTTPS 端点；立即返回 200；异步处理。
29. 安全最佳实践 - Access Scopes：请求最小 scope；记录每个 scope 的用途；定期审查。
30. 安全最佳实践 - Rate Limits：遵守 API rate limits；实现 exponential backoff；监控 API 使用量。
31. 常见 API 认证错误：`Invalid access token` 检查 token 是否有效且 scope 正确；`Shop not found` 验证 shop domain 格式；`Missing access token` 在 header 中包含 `X-Shopify-Access-Token`。
32. 常见 GraphQL 错误：`User errors` 检查响应中的 `userErrors` 字段；`Throttled` 降低请求速率；`Field not found` 验证 API version 支持该字段。
33. 常见 Webhook 问题：`Invalid HMAC` 检查 webhook secret 和验证逻辑；`Delivery failed` 确保 endpoint 在超时内返回 200；`Not receiving webhooks` 检查 webhook 注册和 endpoint URL。
34. 资源参考：Dashboard `https://partners.shopify.com`、Documentation `https://shopify.dev`、GraphiQL Admin `https://shopify.dev/docs/apps/tools/graphiql-admin-api`、Community `https://community.shopify.com`、Status `https://www.shopifystatus.com`。
35. 文档快速参考：搜索所有文档用 `grep -r 'search term' .claude/skills/shopify/docs/`；查找主题用 `ls .claude/skills/shopify/docs/shopify/`；读取具体指南用 `cat .claude/skills/shopify/docs/shopify/webhooks.md`。
36. 常见 doc 文件映射：`api-admin-graphql.md`（GraphQL Admin API）、`api-storefront.md`（Storefront API）、`authentication.md`（OAuth and auth flows）、`webhooks.md`（Webhook handling）、`apps.md`（App development）、`themes.md`（Theme development）、`liquid.md`（Liquid reference）、`hydrogen.md`（Headless commerce）、`checkout.md`（Checkout customization）、`functions.md`（Shopify Functions）、`cli.md`（CLI commands）。

适用边界 · 注意事项

• 不适用于非 Shopify 的电商平台（如 WooCommerce、Magento、BigCommerce）或通用 Web 开发问题；这些场景应使用对应平台文档。
• 不适用于没有 Shopify Partner/开发商店/API 凭据，或无法拉取 `docs/shopify/` 官方文档的环境。
• 不适用于只做 Shopify 后台人工配置、不需要 API、主题、应用或无头开发的任务。