Shopify 开发指南：构建应用、主题、扩展与 API 集成完整教程

shopify-development by sickn33/antigravity-awesome-skills

991 周安装量

27,400 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/sickn33/antigravity-awesome-skills --skill shopify-development

开发云服务 API

🇨🇳中文介绍

Shopify 开发技能

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

构建 Shopify 应用或扩展
创建结账/管理后台/POS 界面自定义功能
使用 Liquid 模板开发主题
与 Shopify GraphQL 或 REST API 集成
实现 Webhook 或计费功能
处理元字段或 Shopify Functions

路由：构建什么

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

如果用户想要自定义结账流程或添加管理后台界面或创建 POS 操作或实现折扣规则： → 构建一个扩展（参见 references/extensions.md）

如果用户想要自定义店铺前端设计或修改产品/集合页面： → 构建一个主题（参见 references/themes.md）

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

Shopify CLI 命令

安装 CLI：

npm install -g @shopify/cli@latest

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

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
          }
        }
      }
    }
  }
}

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"
    }
  ]
}

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 (isGift && message) {
      applyAttributeChange({
        type: "updateAttribute",
        key: "gift_message",
        value: 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>
  );
}

{% comment %} 产品卡片代码片段 {% 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>

在 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 强制要求的 Webhook（应用审核所需）
[webhooks.privacy_compliance]
customer_data_request_url = "/webhooks/gdpr/data-request"
customer_deletion_url = "/webhooks/gdpr/customer-deletion"
shop_deletion_url = "/webhooks/gdpr/shop-deletion"

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

将 API 凭证存储在环境变量中
处理前始终验证 Webhook 的 HMAC 签名
验证 OAuth 状态参数以防止 CSRF 攻击
请求最小必要的访问权限范围
嵌入式应用使用会话令牌

数据不频繁变化时缓存 API 响应
在扩展中使用懒加载
在主题中使用 img_url 过滤器优化图片
通过响应头监控 GraphQL 查询成本

如果看到速率限制错误： → 实现指数退避重试逻辑 → 对于大型数据集切换到批量操作 → 监控 X-Shopify-Shop-Api-Call-Limit 响应头

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

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

如果 Webhook 未接收到事件： → 验证 Webhook URL 是否可公开访问 → 检查 HMAC 签名验证逻辑 → 在合作伙伴仪表板中查看 Webhook 日志

如果 GraphQL 查询失败： → 根据模式验证查询（使用 GraphiQL 浏览器） → 检查错误信息中是否有已弃用的字段 → 验证您是否拥有必需的访问权限范围

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

references/app-development.md - OAuth 身份验证流程、产品/订单/计费的 GraphQL 变更操作、Webhook 处理器、计费 API 集成
references/extensions.md - 结账 UI 组件、管理后台 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 开发者文档：https://shopify.dev/docs
GraphQL 管理 API 参考：https://shopify.dev/docs/api/admin-graphql
Shopify CLI 参考：https://shopify.dev/docs/api/shopify-cli
Polaris 设计系统：https://polaris.shopify.com

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

此技能适用于执行概述中描述的工作流程或操作。

2026 年 1 月 19 日

🇺🇸English

Shopify Development Skill

Use this skill when the user asks about:

Building Shopify apps or extensions
Creating checkout/admin/POS UI customizations
Developing themes with Liquid templating
Integrating with Shopify GraphQL or REST APIs
Implementing webhooks or billing
Working with metafields or Shopify Functions

ROUTING: What to Build

IF user wants to integrate external services OR build merchant tools OR charge for features: → Build an App (see references/app-development.md)

IF user wants to customize checkout OR add admin UI OR create POS actions OR implement discount rules: → Build an Extension (see references/extensions.md)

IF user wants to customize storefront design OR modify product/collection pages: → Build a Theme (see references/themes.md)

IF user needs both backend logic AND storefront UI: → Build App + Theme Extension combination

Shopify CLI Commands

Install CLI:

npm install -g @shopify/cli@latest

Create and run app:

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

Generate extension:

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

Theme development:

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

Access Scopes

Configure in shopify.app.toml:

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

Common scopes:

read_products, write_products - Product catalog access
read_orders, write_orders - Order management
read_customers, write_customers - Customer data
read_inventory, write_inventory - Stock levels
read_fulfillments, write_fulfillments - Order fulfillment

GraphQL Patterns (Validated against API 2026-01)

Query Products

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 Orders

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

Set Metafields

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

Variables example:

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

Checkout Extension Example

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 (isGift && message) {
      applyAttributeChange({
        type: "updateAttribute",
        key: "gift_message",
        value: 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 Template Example

{% 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 Configuration

In 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.privacy_compliance]
customer_data_request_url = "/webhooks/gdpr/data-request"
customer_deletion_url = "/webhooks/gdpr/customer-deletion"
shop_deletion_url = "/webhooks/gdpr/shop-deletion"

Best Practices

API Usage

Use GraphQL over REST for new development
Request only fields you need (reduces query cost)
Implement cursor-based pagination with pageInfo.endCursor
Use bulk operations for processing more than 250 items
Handle rate limits with exponential backoff

Security

Store API credentials in environment variables
Always verify webhook HMAC signatures before processing
Validate OAuth state parameter to prevent CSRF
Request minimal access scopes
Use session tokens for embedded apps

Performance

Cache API responses when data doesn't change frequently
Use lazy loading in extensions
Optimize images in themes using img_url filter
Monitor GraphQL query costs via response headers

Troubleshooting

IF you see rate limit errors: → Implement exponential backoff retry logic → Switch to bulk operations for large datasets → Monitor X-Shopify-Shop-Api-Call-Limit header

IF authentication fails: → Verify the access token is still valid → Check that all required scopes were granted → Ensure OAuth flow completed successfully

IF extension is not appearing: → Verify the extension target is correct → Check that extension is published via shopify app deploy → Confirm the app is installed on the test store

IF webhook is not receiving events: → Verify the webhook URL is publicly accessible → Check HMAC signature validation logic → Review webhook logs in Partner Dashboard

IF GraphQL query fails: → Validate query against schema (use GraphiQL explorer) → Check for deprecated fields in error message → Verify you have required access scopes

Reference Files

For detailed implementation guides, read these files:

references/app-development.md - OAuth authentication flow, GraphQL mutations for products/orders/billing, webhook handlers, billing API integration
references/extensions.md - Checkout UI components, Admin UI extensions, POS extensions, Shopify Functions for discounts/payment/delivery
references/themes.md - Liquid syntax reference, theme directory structure, sections and snippets, common patterns

Scripts

scripts/shopify_init.py - Interactive project scaffolding. Run: python scripts/shopify_init.py
scripts/shopify_graphql.py - GraphQL utilities with query templates, pagination, rate limiting. Import: from shopify_graphql import ShopifyGraphQL

Official Documentation Links

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 Version: 2026-01 (quarterly releases, 12-month deprecation window)

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Weekly Installs

991

Repository

sickn33/antigra…e-skills

GitHub Stars

27.4K

First Seen

Jan 19, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode798

gemini-cli775

codex756

github-copilot687

cursor671

claude-code633

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

102,200 周安装

Shopify 开发指南：构建应用、主题、扩展与 API 集成完整教程

🇨🇳中文介绍

Shopify 开发技能

路由：构建什么

Shopify CLI 命令

相关 Skills

访问权限范围

GraphQL 模式（针对 API 2026-01 版本验证）

查询产品

查询订单

设置元字段

结账扩展示例

Liquid 模板示例

Webhook 配置

最佳实践

API 使用

安全性

性能

故障排除

参考文件

脚本

官方文档链接

使用时机