shopify-developer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shopify Developer Reference

Shopify 开发者参考文档

Comprehensive reference for professional Shopify development - API version 2026-01.

面向专业Shopify开发者的全面参考文档 - API版本 2026-01。

Quick Reference

快速参考

Item	Value
API version	`2026-01` (stable)
GraphQL Admin	`POST https://{store}.myshopify.com/admin/api/2026-01/graphql.json`
Storefront API	`POST https://{store}.myshopify.com/api/2026-01/graphql.json`
Ajax API (theme)	`/cart.js` , `/cart/add.js` , `/cart/change.js`
CLI install	`npm install -g @shopify/cli`
Theme dev	`shopify theme dev --store {store}.myshopify.com`
App dev	`shopify app dev`
Deploy	`shopify app deploy`
Docs	shopify.dev

项目	取值
API版本	`2026-01` （稳定版）
GraphQL Admin	`POST https://{store}.myshopify.com/admin/api/2026-01/graphql.json`
Storefront API	`POST https://{store}.myshopify.com/api/2026-01/graphql.json`
Ajax API（主题）	`/cart.js` , `/cart/add.js` , `/cart/change.js`
CLI 安装	`npm install -g @shopify/cli`
主题开发	`shopify theme dev --store {store}.myshopify.com`
应用开发	`shopify app dev`
部署	`shopify app deploy`
官方文档	shopify.dev

Choose Your Path

选择你的学习路径

Read the reference file(s) that match your task:

Liquid templating - writing or debugging

.liquid

files:

references/liquid-syntax.md - Tags, control flow, iteration, whitespace, LiquidDoc
references/liquid-filters.md - All filter categories with examples
references/liquid-objects.md - Product, collection, cart, customer, and global objects

Theme development - building or customising themes:

references/theme-development.md - OS 2.0 architecture, sections, blocks, JSON templates, settings schema

API integration - fetching or modifying data programmatically:

references/api-admin.md - GraphQL Admin API (primary), REST (legacy), OAuth, webhooks, rate limiting
references/api-storefront.md - Storefront API, Ajax API, cart operations

App development - building Shopify apps:

references/app-development.md - Shopify CLI, extensions, Polaris Web Components, App Bridge

Serverless logic - custom business rules:

references/functions.md - Shopify Functions (replacing Scripts), Rust/JS targets, deployment

Headless commerce - custom storefronts:

references/hydrogen.md - Hydrogen framework, React Router 7, Storefront API integration

Optimisation and troubleshooting:

references/performance.md - Images, JS, CSS, fonts, Liquid, Core Web Vitals
references/debugging.md - Liquid errors, API errors, cart issues, webhook failures

阅读与你的任务匹配的参考文件：

Liquid模板 - 编写或调试

.liquid

文件：

references/liquid-syntax.md - 标签、控制流、迭代、空白处理、LiquidDoc
references/liquid-filters.md - 所有过滤器分类及示例
references/liquid-objects.md - 商品、集合、购物车、客户及全局对象

主题开发 - 构建或自定义主题：

references/theme-development.md - OS 2.0架构、区块、组件、JSON模板、设置模式

API集成 - 以编程方式获取或修改数据：

references/api-admin.md - GraphQL Admin API（主要）、REST（遗留）、OAuth、Webhook、速率限制
references/api-storefront.md - Storefront API、Ajax API、购物车操作

应用开发 - 构建Shopify应用：

references/app-development.md - Shopify CLI、扩展、Polaris Web Components、App Bridge

无服务器逻辑 - 自定义业务规则：

references/functions.md - Shopify Functions（替代Scripts）、Rust/JS目标、部署

无头电商 - 自定义店铺前端：

references/hydrogen.md - Hydrogen框架、React Router 7、Storefront API集成

优化与故障排查：

references/performance.md - 图片、JS、CSS、字体、Liquid、Core Web Vitals
references/debugging.md - Liquid错误、API错误、购物车问题、Webhook失败

Deprecation Notices

废弃通知

Deprecated	Replacement	Deadline
Shopify Scripts	Shopify Functions	August 2025 (migration), sundown TBD
checkout.liquid	Checkout Extensibility	August 2024 (Plus), done
REST Admin API	GraphQL Admin API	Active deprecation (no removal date yet)
Legacy custom apps	New auth model	January 2025 (done)
Polaris React	Polaris Web Components	Active migration
Remix (app framework)	React Router 7	Hydrogen 2025.5.0+

废弃项	替代方案	截止日期
Shopify Scripts	Shopify Functions	2025年8月（迁移截止），停用日期待定
checkout.liquid	Checkout Extensibility	2024年8月（Plus版），已完成废弃
REST Admin API	GraphQL Admin API	正在逐步废弃（暂未确定移除日期）
旧版自定义应用	新认证模型	2025年1月（已完成废弃）
Polaris React	Polaris Web Components	正在迁移中
Remix（应用框架）	React Router 7	Hydrogen 2025.5.0及以上版本

Liquid Essentials

Liquid 核心语法

Three syntax types:

liquid

{{ product.title | upcase }}                    {# Output with filter #}
{% if product.available %}In stock{% endif %}   {# Logic tag #}
{% assign sale = product.price | times: 0.8 %}  {# Assignment #}
{%- if condition -%}Stripped whitespace{%- endif -%}

Key patterns:

liquid

{% for product in collection.products limit: 5 %}
  {% render 'product-card', product: product %}
{% endfor %}

{% paginate collection.products by 12 %}
  {% for product in paginate.collection.products %}...{% endfor %}
  {{ paginate | default_pagination }}
{% endpaginate %}

三种语法类型：

liquid

{{ product.title | upcase }}                    {# 带过滤器的输出 #}
{% if product.available %}有货{% endif %}   {# 逻辑标签 #}
{% assign sale = product.price | times: 0.8 %}  {# 变量赋值 #}
{%- if condition -%}移除空白{%- endif -%}

关键模式：

liquid

{% for product in collection.products limit: 5 %}
  {% render 'product-card', product: product %}
{% endfor %}

{% paginate collection.products by 12 %}
  {% for product in paginate.collection.products %}...{% endfor %}
  {{ paginate | default_pagination }}
{% endpaginate %}

API Essentials

API 核心用法

javascript

// GraphQL Admin - always use GraphQL over REST
const response = await fetch(
  `https://${store}.myshopify.com/admin/api/2026-01/graphql.json`,
  {
    method: 'POST',
    headers: {
      'X-Shopify-Access-Token': accessToken,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query, variables }),
  }
);
const { data, errors } = await response.json();
if (errors) throw new Error(errors[0].message);

// Ajax API (theme-only cart operations)
fetch('/cart/add.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ id: variantId, quantity: 1 }),
});

javascript

// GraphQL Admin - 优先使用GraphQL而非REST
const response = await fetch(
  `https://${store}.myshopify.com/admin/api/2026-01/graphql.json`,
  {
    method: 'POST',
    headers: {
      'X-Shopify-Access-Token': accessToken,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query, variables }),
  }
);
const { data, errors } = await response.json();
if (errors) throw new Error(errors[0].message);

// Ajax API（仅主题可用的购物车操作）
fetch('/cart/add.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ id: variantId, quantity: 1 }),
});

Reference Files

参考文件详情

File	Lines	Coverage
liquid-syntax.md	~600	Tags, control flow, iteration, variables, whitespace, LiquidDoc
liquid-filters.md	~870	String, numeric, array, Shopify-specific, date, URL, colour filters
liquid-objects.md	~695	All Shopify objects: product, variant, collection, cart, customer, order, etc.
theme-development.md	~1200	File structure, JSON templates, sections, blocks, settings schema, layout
api-admin.md	~595	GraphQL queries/mutations, REST (legacy), OAuth, webhooks, rate limiting
api-storefront.md	~235	Storefront API, Ajax API, cart operations, Customer Account API
app-development.md	~760	CLI, app architecture, extensions, Polaris Web Components, deployment
functions.md	~300	Function types, Rust/JS targets, CLI workflow, Scripts migration
hydrogen.md	~375	Setup, routing, data loading, Storefront API, deployment
performance.md	~605	Images, JS, CSS, fonts, Liquid, third-party scripts, Core Web Vitals
debugging.md	~650	Liquid, JavaScript, API, cart, webhook, theme editor troubleshooting

文件	行数	覆盖范围
liquid-syntax.md	~600	标签、控制流、迭代、变量、空白处理、LiquidDoc
liquid-filters.md	~870	字符串、数值、数组、Shopify专属、日期、URL、颜色过滤器
liquid-objects.md	~695	所有Shopify对象：商品、变体、集合、购物车、客户、订单等
theme-development.md	~1200	文件结构、JSON模板、区块、组件、设置模式、布局
api-admin.md	~595	GraphQL查询/变更、REST（遗留）、OAuth、Webhook、速率限制
api-storefront.md	~235	Storefront API、Ajax API、购物车操作、客户账户API
app-development.md	~760	CLI、应用架构、扩展、Polaris Web Components、部署
functions.md	~300	函数类型、Rust/JS目标、CLI工作流、Scripts迁移
hydrogen.md	~375	初始化设置、路由、数据加载、Storefront API、部署
performance.md	~605	图片、JS、CSS、字体、Liquid、第三方脚本、Core Web Vitals
debugging.md	~650	Liquid、JavaScript、API、购物车、Webhook、主题编辑器故障排查