shopify-developer
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseShopify Developer Reference
Shopify 开发参考
Comprehensive reference for professional Shopify development - API version 2026-01.
面向专业Shopify开发的综合参考文档 - API版本 2026-01。
Quick Reference
快速参考
| Item | Value |
|---|---|
| API version | |
| GraphQL Admin | |
| Storefront API | |
| Ajax API (theme) | |
| CLI install | |
| Theme dev | |
| App dev | |
| Deploy | |
| Docs | shopify.dev |
| 项目 | 取值 |
|---|---|
| API 版本 | |
| GraphQL Admin | |
| Storefront API | |
| Ajax API (主题) | |
| CLI 安装 | |
| 主题开发 | |
| 应用开发 | |
| 部署 | |
| 官方文档 | shopify.dev |
Choose Your Path
选择你的学习路径
Read the reference file(s) that match your task:
Liquid templating - writing or debugging files:
.liquid- 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 架构、section、block、JSON模板、设置 schema
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、核心Web指标
- 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 %}In stock{% endif %} {# 逻辑标签 #}
{% assign sale = product.price | times: 0.8 %} {# 变量赋值 #}
{%- if condition -%}Stripped whitespace{%- 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模板、section、block、设置schema、布局 |
| 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 | Function类型、Rust/JS编译目标、CLI工作流、Scripts迁移 |
| hydrogen.md | ~375 | 环境搭建、路由、数据加载、Storefront API、部署 |
| performance.md | ~605 | 图片、JS、CSS、字体、Liquid、第三方脚本、核心Web指标 |
| debugging.md | ~650 | Liquid、JavaScript、API、购物车、webhook、主题编辑器故障排查 |