shopify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shopify Development

Shopify开发

Comprehensive guide for building on Shopify platform: apps, extensions, themes, and API integrations.

Shopify平台开发综合指南：应用、扩展、主题及API集成。

Platform Overview

平台概览

Core Components:

Shopify CLI - Development workflow tool
GraphQL Admin API - Primary API for data operations (recommended)
REST Admin API - Legacy API (maintenance mode)
Polaris UI - Design system for consistent interfaces
Liquid - Template language for themes

Extension Points:

Checkout UI - Customize checkout experience
Admin UI - Extend admin dashboard
POS UI - Point of Sale customization
Customer Account - Post-purchase pages
Theme App Extensions - Embedded theme functionality

核心组件：

Shopify CLI - 开发工作流工具
GraphQL Admin API - 用于数据操作的主API（推荐使用）
REST Admin API - 遗留API（维护模式）
Polaris UI - 用于构建一致界面的设计系统
Liquid - 主题模板语言

扩展点：

Checkout UI - 自定义结账体验
Admin UI - 扩展管理后台仪表盘
POS UI - 收银系统定制
Customer Account - 售后页面
Theme App Extensions - 嵌入式主题功能

Quick Start

快速开始

Prerequisites

前置条件

bash

undefined

bash

undefined

Install Shopify CLI

安装Shopify CLI

npm install -g @shopify/cli@latest

Verify installation

验证安装

shopify version

undefined

shopify version

undefined

Create New App

创建新应用

bash

undefined

bash

undefined

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

undefined

shopify app deploy

undefined

Theme Development

主题开发

bash

undefined

bash

undefined

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

undefined

shopify theme push --development

undefined

Development Workflow

开发工作流

1. App Development

1. 应用开发

Setup:

bash

shopify app init
cd my-app

Configure Access Scopes (

shopify.app.toml

toml

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

Start Development:

bash

shopify app dev  # Starts local server with tunnel

Add Extensions:

bash

shopify app generate extension --type checkout_ui_extension

Deploy:

bash

shopify app deploy  # Builds and uploads to Shopify

设置：

bash

shopify app init
cd my-app

配置访问权限范围 (

shopify.app.toml

toml

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

启动开发：

bash

shopify app dev  # 启动带隧道的本地服务器

添加扩展：

bash

shopify app generate extension --type checkout_ui_extension

部署：

bash

shopify app deploy  # 构建并上传至Shopify

2. Extension Development

2. 扩展开发

Available Types:

Checkout UI -
```
checkout_ui_extension
```
Admin Action -
```
admin_action
```
Admin Block -
```
admin_block
```
POS UI -
```
pos_ui_extension
```
Function -
```
function
```
(discounts, payment, delivery, validation)

Workflow:

bash

shopify app generate extension

可用类型：

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

工作流：

bash

shopify app generate extension

Select type, configure

选择类型，完成配置

shopify app dev # Test locally shopify app deploy # Publish

undefined

shopify app dev # 本地测试 shopify app deploy # 发布

undefined

3. Theme Development

3. 主题开发

Setup:

bash

shopify theme init

设置：

bash

shopify theme init

Choose Dawn (reference theme) or start fresh

选择Dawn（参考主题）或从零开始


**Local Development:**
```bash
shopify theme dev


**本地开发：**
```bash
shopify theme dev

Preview at localhost:9292

在localhost:9292预览

Auto-syncs to development theme

自动同步到开发主题


**Deployment:**
```bash
shopify theme push --development  # Push to dev theme
shopify theme publish --theme=123  # Set as live


**部署：**
```bash
shopify theme push --development  # 推送到开发主题
shopify theme publish --theme=123  # 设置为在线主题

When to Build What

不同场景的选择

Build an App When:

以下场景适合构建应用：

Integrating external services
Adding functionality across multiple stores
Building merchant-facing admin tools
Managing store data programmatically
Implementing complex business logic
Charging for functionality

集成外部服务
为多个店铺添加功能
构建面向商家的管理工具
程序化管理店铺数据
实现复杂业务逻辑
为功能收取费用

Build an Extension When:

以下场景适合构建扩展：

Customizing checkout flow
Adding fields/features to admin pages
Creating POS actions for retail
Implementing discount/payment/shipping rules
Extending customer account pages

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

Build a Theme When:

以下场景适合构建主题：

Creating custom storefront design
Building unique shopping experiences
Customizing product/collection pages
Implementing brand-specific layouts
Modifying homepage/content pages

创建自定义店铺前端设计
打造独特购物体验
自定义商品/集合页面
实现品牌专属布局
修改首页/内容页面

Combination Approach:

组合方案：

App + Theme Extension:

App handles backend logic and data
Theme extension provides storefront UI
Example: Product reviews, wishlists, size guides

应用+主题扩展：

应用处理后端逻辑和数据
主题扩展提供店铺前端UI
示例：商品评价、心愿单、尺码指南

Essential Patterns

核心模式

GraphQL Product Query

GraphQL商品查询

graphql

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

graphql

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

Checkout Extension (React)

结账扩展（React实现）

javascript

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

javascript

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 Product Display

Liquid商品展示

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

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

Best Practices

最佳实践

API Usage:

Prefer GraphQL over REST for new development
Request only needed fields to reduce costs
Implement pagination for large datasets
Use bulk operations for batch processing
Respect rate limits (cost-based for GraphQL)

Security:

Store API credentials in environment variables
Verify webhook signatures
Use OAuth for public apps
Request minimal access scopes
Implement session tokens for embedded apps

Performance:

Cache API responses when appropriate
Optimize images in themes
Minimize Liquid logic complexity
Use async loading for extensions
Monitor query costs in GraphQL

Testing:

Use development stores for testing
Test across different store plans
Verify mobile responsiveness
Check accessibility (keyboard, screen readers)
Validate GDPR compliance

API使用：

新项目优先使用GraphQL而非REST
仅请求所需字段以降低成本
为大数据集实现分页
批量操作使用批量处理功能
遵守速率限制（GraphQL基于成本计算）

安全：

将API凭证存储在环境变量中
验证Webhook签名
公开应用使用OAuth认证
请求最小必要的权限范围
嵌入式应用使用会话令牌

性能：

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

测试：

使用开发店铺进行测试
在不同店铺套餐中测试
验证移动端响应式
检查可访问性（键盘、屏幕阅读器）
验证GDPR合规性

Reference Documentation

参考文档

Detailed guides for advanced topics:

App Development - OAuth, APIs, webhooks, billing
Extensions - Checkout, Admin, POS, Functions
Themes - Liquid, sections, deployment

高级主题的详细指南：

应用开发 - OAuth、API、Webhook、账单
扩展 - 结账、管理后台、POS、功能扩展
主题 - Liquid、区块、部署

Scripts

脚本

shopify_init.py - Initialize Shopify projects interactively

bash

python scripts/shopify_init.py

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

bash

python scripts/shopify_init.py

Troubleshooting

故障排查

Rate Limit Errors:

Monitor
```
X-Shopify-Shop-Api-Call-Limit
```
header
Implement exponential backoff
Use bulk operations for large datasets

Authentication Failures:

Verify access token validity
Check required scopes granted
Ensure OAuth flow completed

Extension Not Appearing:

Verify extension target correct
Check extension published
Ensure app installed on store

Webhook Not Receiving:

Verify webhook URL accessible
Check signature validation
Review logs in Partner Dashboard

速率限制错误：

监控
```
X-Shopify-Shop-Api-Call-Limit
```
响应头
实现指数退避策略
大数据集使用批量操作

认证失败：

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

扩展未显示：

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

Webhook未接收：

验证Webhook URL可访问
检查签名验证设置
查看合作伙伴仪表盘日志

Resources

资源

Official Documentation:

Shopify Docs: 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

Tools:

GraphiQL Explorer (Admin → Settings → Apps → Develop apps)
Partner Dashboard (app management)
Development stores (free testing)

API Versioning:

Quarterly releases (YYYY-MM format)
Current: 2025-01
12-month support per version
Test before version updates

Note: This skill covers Shopify platform as of January 2025. Refer to official documentation for latest updates.

官方文档：

Shopify Docs: 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（管理后台 → 设置 → 应用 → 开发应用）
合作伙伴仪表盘（应用管理）
开发店铺（免费测试）

API版本控制：

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

注意： 本指南涵盖截至2025年1月的Shopify平台内容。最新信息请参考官方文档。