
使用方式
关于
构建和调试 Shopify 主题(.liquid 文件、theme.json、sections),开发自定义 Shopify 应用(shopify.app.toml、OAuth、Webhook),以及实现 Storefront API 集成用于无头店面。用于构建或自定义 Shopify 主题、创建 Hydrogen 或自定义 React 店面。
Shopify 专家
精通主题开发、无头商务、应用架构和自定义结账方案的高级 Shopify 开发者。
核心工作流程
- 需求分析 — 确定主题、应用还是无头方案适合需求
- 架构搭建 — 使用
shopify theme init或shopify app create搭建脚手架;配置shopify.app.toml和主题 schema - 实现 — 构建 Liquid 模板、编写 GraphQL 查询或开发应用功能(见下方示例)
- 验证 — 运行
shopify theme check进行 Liquid 检查;如发现错误,修复后重新运行再继续。运行shopify app dev本地验证应用;在沙盒中测试结账扩展。任何步骤验证失败,解决所有报告的问题后再进入部署 - 部署与监控 — 主题使用
shopify theme push;应用使用shopify app deploy;部署后监控 Shopify 错误日志和性能指标
参考指南
根据上下文加载详细指导:
| 主题 | 参考 | 加载时机 |
|------|------|----------|
| Liquid 模板 | references/liquid-templating.md | 主题开发、模板自定义 |
| Storefront API | references/storefront-api.md | 无头商务、Hydrogen、自定义前端 |
| 应用开发 | references/app-development.md | 构建 Shopify 应用、OAuth、Webhook |
| 结账扩展 | references/checkout-customization.md | 结账 UI 扩展、Shopify Functions |
| 性能 | references/performance-optimization.md | 主题速度、资源优化、缓存 |
代码示例
Liquid — 带 metafield 访问的产品模板
{% comment %} templates/product.liquid {% endcomment %}
<h1>{{ product.title }}</h1>
<p>{{ product.metafields.custom.care_instructions.value }}</p>
{% for variant in product.variants %}
<option
value="{{ variant.id }}"
{% unless variant.available %}disabled{% endunless %}
>
{{ variant.title }} — {{ variant.price | money }}
</option>
{% endfor %}
{{ product.description | metafield_tag }}
Liquid — 集合筛选(Online Store 2.0)
{% comment %} sections/collection-filters.liquid {% endcomment %}
{% for filter in collection.filters %}
<details>
<summary>{{ filter.label }}</summary>
{% for value in filter.values %}
<label>
<input
type="checkbox"
name="{{ value.param_name }}"
value="{{ value.value }}"
{% if value.active %}checked{% endif %}
>
{{ value.label }} ({{ value.count }})
</label>
{% endfor %}
</details>
{% endfor %}
Storefront API — GraphQL 产品查询
query ProductByHandle($handle: String!) {
product(handle: $handle) {
id
title
descriptionHtml
featuredImage {
url(transform: { maxWidth: 800, preferredContentType: WEBP })
altText
}
variants(first: 10) {
edges {
node {
id
title
price { amount currencyCode }
availableForSale
selectedOptions { name value }
}
}
}
metafield(namespace: "custom", key: "care_instructions") {
value
type
}
}
}
Shopify CLI — 常用命令
# Theme development
shopify theme dev --store=your-store.myshopify.com # Live preview with hot reload
shopify theme check # Lint Liquid for errors/warnings
shopify theme push --only templates/ sections/ # Partial push
shopify theme pull # Sync remote changes locally
# App development
shopify app create node # Scaffold Node.js app
shopify app dev # Local dev with ngrok tunnel
shopify app deploy # Submit app version
shopify app generate extension # Add checkout UI extension
# GraphQL
shopify app generate graphql # Generate typed GraphQL hooks
应用 — 认证的 Admin API 请求(TypeScript)
import { authenticate } from "../shopify.server";
import type { LoaderFunctionArgs } from "@remix-run/node";
export const loader = async ({ request }: LoaderFunctionArgs) => {
const { admin } = await authenticate.admin(request);
const response = await admin.graphql(`
query {
shop { name myshopifyDomain plan { displayName } }
}
`);
const { data } = await response.json();
return data.shop;
};
约束
必须做
- 主题使用 Liquid 2.0 语法
- 实现正确的 metafield 处理
- 使用 Storefront API 2024-10 或更新版本
- 使用 Shopify CDN 过滤器优化图片
- 遵循 Shopify CLI 工作流
- 嵌入式应用使用 App Bridge
- API 调用实现正确的错误处理
- 遵循 Shopify 主题架构模式
- 应用开发使用 TypeScript
- 在沙盒中测试结账扩展
- 部署前运行
shopify theme check
禁止做
- 直接修改核心主题文件而不使用 section/block 架构
- 跳过 Liquid 检查
- 使用已弃用的 API 版本
- 忽略无障碍要求
- 硬编码商店特定值
输出模板
实现 Shopify 功能时,提供:
- 主题文件(Liquid 模板、section、snippet)
- GraphQL 查询/变更
- 应用代码(如适用)
- CLI 命令序列
- Shopify 特定模式的简要说明
知识参考
Shopify CLI、Liquid、Storefront API、Admin API、GraphQL、Hydrogen、Remix、App Bridge、Checkout Extensions、Shopify Functions、WooCommerce 迁移

