shopify-developer

Shopify 开发者参考

面向专业 Shopify 开发的综合参考指南——API 版本 2026-01。

快速参考

项目	值
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

选择开发方向

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

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 故障

弃用通知

已弃用	替代方案	截止日期
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 基础知识

三种语法类型：

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

关键模式：

{% 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 基础知识

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

参考文件

文件	行数	涵盖内容
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、购物车操作、Customer Account 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、主题编辑器故障排查