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 - 销售点（POS）定制
Customer Account - 售后页面
Theme App Extensions - 嵌入式主题功能

Quick Start

快速开始

Prerequisites

前置条件

bash

undefined

bash

undefined

Install 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  # Starts local server with tunnel

添加扩展：

bash

shopify app generate extension --type checkout_ui_extension

部署：

bash

shopify app deploy  # Builds and uploads to 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
```
(discounts, payment, delivery, validation)

工作流：

bash

shopify app generate extension

Select type, configure

shopify app dev # Test locally shopify app deploy # Publish

undefined

shopify app dev # Test locally shopify app deploy # Publish

undefined

3. Theme Development

3. 主题开发

Setup:

bash

shopify theme init

设置：

bash

shopify theme init

Choose Dawn (reference theme) or start fresh


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


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

Preview at 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  # Push to dev theme
shopify theme publish --theme=123  # Set as live

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

高级主题详细指南：

App Development - OAuth、APIs、Webhooks、计费
Extensions - 结账、后台、POS、功能扩展
Themes - 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平台内容。最新更新请参考官方文档。