shopify-development

Shopify 开发技能

在用户询问以下内容时使用此技能：

• 构建 Shopify 应用或扩展
• 创建结账页／后台／POS UI 自定义项
• 使用 Liquid 模板开发主题
• 集成 Shopify GraphQL 或 REST API
• 实现 Webhook 或计费功能
• 使用 metafield 或 Shopify Functions

---

路由：构建什么

如果用户想要集成外部服务，或构建商家工具，或为功能收费： → 构建 应用（参见 references/app-development.md）

如果用户想要自定义结账页，或添加后台 UI，或创建 POS 操作，或实现折扣规则： → 构建 扩展（参见 references/extensions.md）

如果用户想要自定义店面设计，或修改产品／系列页面： → 构建 主题（参见 references/themes.md）

如果用户同时需要后端逻辑和店面 UI： → 构建 应用 + 主题扩展组合

---

执行与版本边界

固定 CLI/API 版本。示例是脚手架草图，未经部署测试。 应用部署、主题上传、履约、计费和数据导出都需要获得授权的商店、作用域和预期效果。对于结果不明确的变更操作，不要重试。 初始化程序仅生成部分配置，会拒绝已有的项目文件夹，并且仅在设置 SHOPIFY_LOAD_ENV_FILES=1 时加载 .env 文件。优先使用 CLI 生成的项目。 开发隧道会将端点暴露给外部；请使用测试数据。

Shopify CLI 命令

安装 CLI：

npm install -g @shopify/cli@latest

创建并运行应用：

shopify app init          # Create new app
shopify app dev           # Start dev server with tunnel
shopify app deploy        # Build and upload to Shopify

生成扩展：

shopify app generate extension --type checkout_ui_extension
shopify app generate extension --type admin_action
shopify app generate extension --type admin_block
shopify app generate extension --type pos_ui_extension
shopify app generate extension --type function

主题开发：

shopify theme init        # Create new theme
shopify theme dev         # Start local preview at localhost:9292
shopify theme pull --live # Pull live theme
shopify theme push --development  # Push to dev theme

---

访问作用域

在 shopify.app.toml 中配置：

[access_scopes]
scopes = "read_products,write_products,read_orders,write_orders,read_customers"

常见作用域：

• read_products、write_products - 产品目录访问权限
• read_orders、write_orders - 订单管理
• read_customers、write_customers - 客户数据
• read_inventory、write_inventory - 库存水平
• read_fulfillments、write_fulfillments - 订单履约

---

GraphQL 模式（示例 API 2026-01）

查询产品

query GetProducts($first: Int!, $query: String) {
  products(first: $first, query: $query) {
    edges {
      node {
        id
        title
        handle
        status
        variants(first: 5) {
          edges {
            node {
              id
              price
              inventoryQuantity
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

查询订单

query GetOrders($first: Int!) {
  orders(first: $first) {
    edges {
      node {
        id
        name
        createdAt
        displayFinancialStatus
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
      }
    }
  }
}

设置 Metafield

mutation SetMetafields($metafields: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $metafields) {
    metafields {
      id
      namespace
      key
      value
    }
    userErrors {
      field
      message
    }
  }
}

变量示例：

{
  "metafields": [
    {
      "ownerId": "gid://shopify/Product/123",
      "namespace": "custom",
      "key": "care_instructions",
      "value": "Handle with care",
      "type": "single_line_text_field"
    }
  ]
}

---

结账页扩展示例（旧版 React API）

此 React 示例面向较旧的扩展 API，而非 2026-01。对于当前 API，请使用固定版本的 CLI 生成 Preact 扩展；不要将 React hooks／组件与 2026-01 web 组件混用。取消勾选时清除礼品属性，并在使用此草图前处理变更失败。

import {useState, useEffect} from "react";
import {
  reactExtension,
  BlockStack,
  TextField,
  Checkbox,
  useApplyAttributeChange,
} from "@shopify/ui-extensions-react/checkout";

export default reactExtension("purchase.checkout.block.render", () => (
  <GiftMessage />
));

function GiftMessage() {
  const [isGift, setIsGift] = useState(false);
  const [message, setMessage] = useState("");
  const applyAttributeChange = useApplyAttributeChange();

  useEffect(() => {
    if (true) { // Also clear a previously saved message when gift is unchecked
      applyAttributeChange({
        type: "updateAttribute",
        key: "gift_message",
        value: isGift ? message : "",
      });
    }
  }, [isGift, message]);

  return (
    <BlockStack spacing="loose">
      <Checkbox checked={isGift} onChange={setIsGift}>
        This is a gift
      </Checkbox>
      {isGift && (
        <TextField
          label="Gift Message"
          value={message}
          onChange={setMessage}
          multiline={3}
        />
      )}
    </BlockStack>
  );
}

---

Liquid 模板示例

{% comment %} Product Card Snippet {% endcomment %}
<div class="product-card">
  <a href="{{ product.url }}">
    {% if product.featured_image %}
      <img
        src="{{ product.featured_image | img_url: 'medium' }}"
        alt="{{ product.title | escape }}"
        loading="lazy"
      >
    {% endif %}
    <h3>{{ product.title }}</h3>
    <p class="price">{{ product.price | money }}</p>
    {% if product.compare_at_price > product.price %}
      <p class="sale-badge">Sale</p>
    {% endif %}
  </a>
</div>

---

Webhook 配置

在 shopify.app.toml 中：

[webhooks]
api_version = "2026-01"

[[webhooks.subscriptions]]
topics = ["orders/create", "orders/updated"]
uri = "/webhooks/orders"

[[webhooks.subscriptions]]
topics = ["products/update"]
uri = "/webhooks/products"

# GDPR mandatory webhooks (required for app approval)
[[webhooks.subscriptions]]
compliance_topics = ["customers/data_request", "customers/redact", "shop/redact"]
uri = "/webhooks/privacy"

---

最佳实践

API 使用

• 新开发项目优先使用 GraphQL，而非 REST
• 仅请求所需字段（可降低查询成本）
• 使用 pageInfo.endCursor 实现基于游标的分页
• 使用批量操作处理超过 250 个项目
• 使用指数退避处理速率限制

安全性

• 将 API 凭据存储在环境变量中
• 处理 Webhook 前，务必验证 HMAC 签名
• 验证 OAuth state 参数以防止 CSRF
• 请求最小必要的访问作用域
• 嵌入式应用使用会话令牌

性能

• 数据不会频繁变化时，缓存 API 响应
• 在扩展中使用延迟加载
• 在主题中使用 img_url 过滤器优化图片
• 监控响应 extensions.cost 对象中的 GraphQL 查询成本

故障排除

如果遇到速率限制错误： → 实现指数退避重试逻辑 → 对大型数据集改用批量操作 → 检查 GraphQL extensions.cost.throttleStatus；调用限制标头适用于 REST

如果身份验证失败： → 确认访问令牌仍然有效 → 检查是否已授予所有必需的权限范围 → 确保 OAuth 流程已成功完成

如果扩展未显示： → 确认扩展目标正确 → 检查扩展是否已通过 shopify app deploy 发布 → 确认应用已安装在测试商店中

如果 Webhook 未收到事件： → 确认 Webhook URL 可从公网访问 → 检查 HMAC 签名验证逻辑 → 查看 Partner Dashboard 中的 Webhook 日志

如果 GraphQL 查询失败： → 根据架构验证查询（使用 GraphiQL explorer） → 检查错误消息中是否有已弃用的字段 → 确认你具有所需的访问权限范围

---

参考文件

如需详细的实现指南，请阅读以下文件：

• references/app-development.md - OAuth 身份验证流程、用于产品/订单/账单的 GraphQL mutations、Webhook 处理程序、账单 API 集成
• references/extensions.md - Checkout UI 组件、Admin UI 扩展、POS 扩展、用于折扣/支付/配送的 Shopify Functions
• references/themes.md - Liquid 语法参考、主题目录结构、区块和代码片段、常见模式

---

脚本

• scripts/shopify_init.py - 交互式项目脚手架。运行：python scripts/shopify_init.py
• scripts/shopify_graphql.py - 包含查询模板、分页和速率限制功能的 GraphQL 实用工具。导入：from shopify_graphql import ShopifyGraphQL

---

官方文档链接

• Shopify Developer Docs：https://shopify.dev/docs
• GraphQL Admin API Reference：https://shopify.dev/docs/api/admin-graphql
• Shopify CLI Reference：https://shopify.dev/docs/api/shopify-cli
• Polaris Design System：https://polaris.shopify.com

API 版本：2026-01（按季度发布，弃用窗口为 12 个月）

适用场景

当需要执行概述中描述的工作流或操作时，可使用此技能。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为针对特定环境进行验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。