shopify

Shopify 开发

在 Shopify 平台上构建应用、扩展、主题和 API 集成的综合指南。

平台概览

核心组件：

• Shopify CLI - 开发工作流工具
• GraphQL Admin API - 数据操作的主要 API（推荐）
• REST Admin API - 旧版 API（维护模式）
• Polaris UI - 用于打造一致界面的设计系统
• Liquid - 主题模板语言

扩展点：

• Checkout UI - 自定义结账体验
• Admin UI - 扩展管理后台
• POS UI - 自定义销售点
• Customer Account - 购买后的页面
• Theme App Extensions - 嵌入主题的功能

快速入门

前提条件

# Install Shopify CLI
npm install -g @shopify/cli@latest

# Verify installation
shopify version

创建新应用

# Initialize app
shopify app init

# Start development server
shopify app dev

# Generate extension
shopify app generate extension --type checkout_ui_extension

# Deploy
shopify app deploy

主题开发

# Initialize theme
shopify theme init

# Start local preview
shopify theme dev

# Pull from store
shopify theme pull --live

# Push to store
shopify theme push --development

开发工作流

1. 应用开发

设置：

shopify app init
cd my-app

配置访问范围（shopify.app.toml）：

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

开始开发：

shopify app dev  # Starts local server with tunnel

添加扩展：

shopify app generate extension --type checkout_ui_extension

部署：

shopify app deploy  # Builds and uploads to Shopify

2. 扩展开发

可用类型：

• Checkout UI - checkout_ui_extension
• Admin Action - admin_action
• Admin Block - admin_block
• POS UI - pos_ui_extension
• Function - function（折扣、支付、配送、验证）

工作流：

shopify app generate extension
# Select type, configure
shopify app dev  # Test locally
shopify app deploy  # Publish

3. 主题开发

设置：

shopify theme init
# Choose Dawn (reference theme) or start fresh

本地开发：

shopify theme dev
# Preview at localhost:9292
# Auto-syncs to development theme

部署：

shopify theme push --development  # Push to dev theme
shopify theme publish --theme=123  # Set as live

何时构建什么

适合构建应用的场景：

• 集成外部服务
• 为多个商店添加功能
• 构建面向商家的管理工具
• 通过编程方式管理商店数据
• 实现复杂业务逻辑
• 对功能收费

适合构建扩展的场景：

• 自定义结账流程
• 为管理页面添加字段或功能
• 为零售场景创建 POS 操作
• 实现折扣、支付或配送规则
• 扩展客户账户页面

适合构建主题的场景：

• 创建自定义店面设计
• 打造独特的购物体验
• 自定义产品或系列页面
• 实现品牌专属布局
• 修改主页或内容页面

组合方案：

应用 + 主题扩展：

• 应用负责后端逻辑和数据
• 主题扩展提供店面 UI
• 示例：产品评价、愿望清单、尺码指南

基本模式

GraphQL 产品查询

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

结账扩展（React）

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

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

function Extension() {
  const [message, setMessage] = useState('');

  return (
    <BlockStack>
      <TextField label="Gift Message" value={message} onChange={setMessage} />
    </BlockStack>
  );
}

Liquid 产品展示

{% for product in collection.products %}
  <div class="product-card">
    <img src="{{ product.featured_image | img_url: 'medium' }}" alt="{{ product.title }}">
    <h3>{{ product.title }}</h3>
    <p>{{ product.price | money }}</p>
    <a href="{{ product.url }}">View Details</a>
  </div>
{% endfor %}

最佳实践

API 使用：

• 新开发优先使用 GraphQL，而非 REST
• 仅请求所需字段，以降低成本
• 为大型数据集实现分页
• 使用批量操作进行批处理
• 遵守速率限制（GraphQL 按成本计费）

安全性：

• 将 API 凭据存储在环境变量中
• 验证 Webhook 签名
• 公共应用使用 OAuth
• 仅申请最低限度的访问范围
• 为嵌入式应用实现会话令牌

性能：

• 适时缓存 API 响应
• 优化主题中的图片
• 尽量降低 Liquid 逻辑的复杂性
• 为扩展使用异步加载
• 监控 GraphQL 查询成本

测试：

• 使用开发商店进行测试
• 在不同商店套餐中进行测试
• 验证移动端适配
• 检查无障碍功能（键盘、屏幕阅读器）
• 验证是否符合 GDPR 要求

参考文档

高级主题的详细指南：

• 应用开发 - OAuth、API、Webhook、计费
• 扩展 - Checkout、Admin、POS、Functions
• 主题 - Liquid、分区、部署

脚本

shopify_init.py - 交互式初始化 Shopify 项目

python scripts/shopify_init.py

故障排查

速率限制错误：

• 监控 X-Shopify-Shop-Api-Call-Limit 标头
• 实施指数退避
• 对大型数据集使用批量操作

身份验证失败：

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

扩展未显示：

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

未收到 Webhook：

• 验证 Webhook URL 是否可访问
• 检查签名验证
• 查看 Partner Dashboard 中的日志

资源

官方文档：

• 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

工具：

• GraphiQL Explorer（Admin → Settings → Apps → Develop apps）
• Partner Dashboard（应用管理）
• 开发商店（免费测试）

API 版本管理：

• 每季度发布（YYYY-MM 格式）
• 当前版本：2025-01
• 每个版本支持 12 个月
• 更新版本前进行测试

---

**注意：**本技能介绍截至 2025 年 1 月的 Shopify 平台。请参阅官方文档以获取最新更新。