名称: shopify 描述: 使用GraphQL/REST API、Shopify CLI、Polaris UI和各种扩展类型（结账、管理、POS）实现Shopify应用、扩展、主题和集成的指南。适用于构建Shopify应用、实现结账扩展、自定义管理界面、使用Liquid创建主题或与Shopify API集成。

Shopify开发

这个技能提供了在Shopify平台上构建的全面指导，包括应用、扩展、主题和API集成。

何时使用此技能

使用此技能当您需要：

构建Shopify应用（公开或自定义）
创建结账、管理或POS UI扩展
使用Liquid模板开发主题
与Shopify API集成（GraphQL管理API、REST API、商店前端API）
实现Shopify功能（折扣、支付、交付、验证）
使用Hydrogen构建无头商店前端
配置webhooks和元字段
使用Shopify CLI进行开发工作流

核心平台组件

1. Shopify CLI

安装：

npm install -g @shopify/cli@latest

基本命令：

shopify app init - 创建新应用
shopify app dev - 启动本地开发服务器
shopify app deploy - 部署应用到Shopify
shopify app generate extension - 向应用添加扩展
shopify theme dev - 本地预览主题
shopify theme pull/push - 同步主题文件

详细CLI参考，请见reference/cli-commands.md

2. GraphQL管理API（推荐）

**新开发的首选API。**高效、类型安全、灵活。

端点：

https://{shop-name}.myshopify.com/admin/api/2025-01/graphql.json

认证：

headers: {
  'X-Shopify-Access-Token': '您的访问令牌',
  'Content-Type': 'application/json'
}

常见操作：

查询产品、订单、客户、库存
通过变异创建/更新/删除资源
批量操作处理大型数据集
订阅实现实时数据

GraphQL全面参考，请见reference/graphql-admin-api.md

3. REST管理API（维护模式）

仅用于遗留系统。 Shopify推荐所有新开发使用GraphQL。

基础URL：

https://{shop-name}.myshopify.com/admin/api/2025-01/{resource}.json

速率限制：

标准：每秒2个请求
加：每秒4个请求

4. UI框架

Polaris（React）

用于一致Shopify UI的设计系统：

npm install @shopify/polaris

Polaris Web组件

框架无关的组件：

<script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script>

扩展类型

结账UI扩展

使用原生渲染组件自定义结账体验。

生成：

shopify app generate extension --type checkout_ui_extension

配置： shopify.extension.toml

常见组件： View、BlockStack、InlineLayout、Button、TextField、Checkbox、Banner

详细扩展参考，请见reference/ui-extensions.md

管理UI扩展

扩展Shopify管理界面。

类型：

应用块（嵌入原生页面）
应用覆盖（模态体验）
链接（产品/集合/订单页面）

POS扩展

自定义销售点体验。

类型：

智能网格磁贴（快速访问操作）
模态（对话框和表单）
购物车修改（自定义折扣/行项目）

售后扩展

结账完成后的追加销售提供。

目标： purchase.thank-you.block.render

客户账户UI扩展

自定义售后账户页面。

目标： 账户概览、订单状态/索引

Shopify功能

在Shopify基础设施上运行的无服务器后端自定义。

功能类型：

折扣： 购物车、产品、配送、订单折扣
支付定制： 隐藏/重命名/重新排序支付方式
交付定制： 自定义配送选项
订单路由： 履行位置规则
验证： 购物车和结账业务规则
履行约束： 捆绑配送规则

语言： JavaScript、Rust、AssemblyScript

生成：

shopify app generate extension --type function

主题开发

Liquid模板

核心概念：

对象： {{ product.title }} - 输出动态内容
过滤器： {{ product.price | money }} - 转换数据
标签： {% if %} {% for %} {% case %} - 控制流

常见对象：

product - 产品数据
collection - 集合数据
cart - 购物车
customer - 客户账户
shop - 商店信息

架构：

布局： 基础模板
模板： 页面结构
部分： 可重复使用的内容块（在线商店2.0）
片段： 小型组件

开发：

shopify theme dev    # 本地预览
shopify theme pull   # 从商店下载
shopify theme push   # 上传到商店

认证与安全

OAuth 2.0流程

用于公共应用访问商家商店：

重定向商家到授权URL
商家批准访问
接收授权代码
交换代码获取访问令牌
安全存储令牌

访问范围

请求所需的最小权限：

read_products - 查看产品
write_products - 修改产品
read_orders - 查看订单
write_orders - 修改订单

完整范围列表：https://shopify.dev/api/usage/access-scopes

会话令牌

用于Shopify管理中的嵌入式应用，使用App Bridge。

Webhooks

来自Shopify的实时事件通知。

配置： shopify.app.toml

常见主题：

orders/create、orders/updated、orders/paid
products/create、products/update、products/delete
customers/create、customers/update
app/uninstalled

GDPR强制性Webhooks：

customers/data_request
customers/redact
shop/redact

元字段

扩展Shopify资源的自定义数据存储。

所有者： 产品、变体、客户、订单、集合、商店

类型： 文本、数字、日期、URL、JSON、文件参考

访问： 管理API、商店前端API、Liquid模板

最佳实践

性能

使用GraphQL而非REST以提高效率
查询中仅请求所需字段
实现分页处理大型数据集
使用批量操作进行批处理
尊重速率限制（GraphQL基于成本）

用户体验

遵循Polaris设计指南
实现加载状态
提供清晰的错误消息
支持键盘导航
跨设备测试

安全

安全存储API凭证
使用环境变量存储令牌
实施webhook验证
遵循OAuth最佳实践
请求最小访问范围

代码质量

使用TypeScript确保类型安全
编写全面的错误处理
实现指数退避重试逻辑
记录错误以调试
保持依赖更新

测试

使用开发商店进行测试
测试不同商店计划
验证webhook处理
测试应用卸载流程
验证GDPR合规性

开发工作流

初始化应用：
```
shopify app init
```

配置访问范围： 编辑shopify.app.toml：

[access_scopes]
scopes = "read_products,write_products"

启动开发服务器：
```
shopify app dev
```
生成扩展：
```
shopify app generate extension
```
在开发商店测试： 在测试商店安装应用
部署到生产：
```
shopify app deploy
```

常见模式

获取产品（GraphQL）

query {
  products(first: 10) {
    edges {
      node {
        id
        title
        handle
        variants(first: 5) {
          edges {
            node {
              id
              price
              inventoryQuantity
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

创建产品（GraphQL）

mutation {
  productCreate(input: {
    title: "新产品"
    productType: "服装"
    variants: [{
      price: "29.99"
      sku: "SKU123"
    }]
  }) {
    product {
      id
      title
    }
    userErrors {
      field
      message
    }
  }
}

结账扩展（React）

import { useState } from 'react';
import {
  render,
  BlockStack,
  TextField,
  Checkbox,
  useApi
} from '@shopify/ui-extensions-react/checkout';

function Extension() {
  const { extensionPoint } = useApi();
  const [checked, setChecked] = useState(false);

  return (
    <BlockStack>
      <TextField label="礼物消息" />
      <Checkbox checked={checked} onChange={setChecked}>
        这是礼物
      </Checkbox>
    </BlockStack>
  );
}

render('Checkout::Dynamic::Render', () => <Extension />);

资源

文档

官方文档：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

工具

GraphiQL Explorer：内置在Shopify管理中
Shopify CLI：开发工作流
合作伙伴仪表板：应用管理
开发商店：免费测试环境

学习

Shopify开发者变更日志：API更新和弃用
Built for Shopify：应用质量计划
社区论坛：帮助和讨论

参考文档

此技能包括详细参考文档：

GraphQL管理API参考 - 全面API指南
Shopify CLI命令 - 完整CLI参考
UI扩展 - 扩展类型和组件

故障排除

常见问题

速率限制错误：

监控X-Shopify-Shop-Api-Call-Limit头
实现指数退避
使用批量操作处理大型数据集

认证失败：

验证访问令牌是否有效
检查所需范围是否已授予
确保OAuth流程正确完成

未接收Webhook事件：

验证webhook URL可访问
检查webhook签名验证
在合作伙伴仪表板中查看webhook日志

扩展未出现：

验证扩展目标正确
检查扩展已发布
确保应用在商店安装

版本管理

Shopify使用季度API版本化（YYYY-MM格式）：

当前：2025-01
每个版本支持12个月
在季度发布前测试更新
使用版本特定端点

应用分发

自定义应用

单一商家安装，无需审核。

公共应用

Shopify应用商店列表需Shopify审核：

遵循应用要求
完成Built for Shopify标准
定义定价模型
提交审核

注意： 此技能涵盖截至2025年1月的Shopify平台。始终参考官方Shopify文档获取最新更新和API版本。