Shopify Development 是一份面向 Shopify 平台开发的综合指南，涵盖应用、扩展、主题与 API 集成。
一、平台概览 核心组件包括：Shopify CLI（开发工作流工具）、GraphQL Admin API（数据操作的主要 API，推荐使用）、REST Admin API（旧版 API，处于维护模式）、Polaris UI（用于保持一致界面的设计系统）、Liquid（主题模板语言）。 扩展点包括：Checkout UI（自定义结账体验）、Admin UI（扩展管理后台）、POS UI（销售点定制）、Customer Account（购后页面）、Theme App Extensions（嵌入式主题功能）。
二、快速开始 前置条件：安装 Shopify CLI，命令为 npm install -g @shopify/cli@latest，并用 shopify version 验证安装。 创建新应用：shopify app init 初始化应用，shopify app dev 启动开发服务器，shopify app generate extension --type checkout_ui_extension 生成扩展，shopify app deploy 部署。 主题开发：shopify theme init 初始化主题，shopify theme dev 启动本地预览，shopify theme pull --live 从商店拉取，shopify theme push --development 推送到商店。
三、开发工作流
- 应用开发：通过 shopify app init 初始化并进入目录；在 shopify.app.toml 中配置访问范围，例如 scopes = "read_products,write_products,read_orders"；用 shopify app dev 启动带隧道的本地服务器；用 shopify app generate extension --type checkout_ui_extension 添加扩展；用 shopify app deploy 构建并上传到 Shopify。
- 扩展开发：可用类型包括 Checkout UI（checkout_ui_extension）、Admin Action（admin_action）、Admin Block（admin_block）、POS UI（pos_ui_extension）、Function（function，用于折扣、支付、配送、验证）。流程为生成扩展、本地测试、发布。
- 主题开发：用 shopify theme init 初始化，可选择 Dawn 参考主题或从零开始；用 shopify theme dev 在 localhost:9292 预览并自动同步到开发主题；用 shopify theme push --development 推送到开发主题，用 shopify theme publish --theme=123 设为线上主题。
四、何时构建什么 构建应用：集成外部服务、跨多商店添加功能、构建面向商家的管理工具、以编程方式管理商店数据、实现复杂业务逻辑、对功能收费。 构建扩展：自定义结账流程、向管理页面添加字段或功能、为零售创建 POS 操作、实现折扣/支付/配送规则、扩展客户账户页面。 构建主题：创建自定义店面设计、构建独特购物体验、自定义商品/集合页面、实现品牌专属布局、修改首页/内容页面。 组合方式：应用 + 主题扩展，应用处理后端逻辑与数据，主题扩展提供店面 UI，例如商品评论、心愿单、尺码指南。
五、关键模式 GraphQL 商品查询示例：query GetProducts($first: Int!) { products(first: $first) { edges { node { id title handle variants(first: 5) { edges { node { id price inventoryQuantity } } } } } pageInfo { hasNextPage endCursor } } } 结账扩展（React）示例：从 @shopify/ui-extensions-react/checkout 导入 reactExtension、BlockStack、TextField、Checkbox，使用 reactExtension('purchase.checkout.block.render', () => <Extension />)，在组件内用 useState 管理消息并渲染 BlockStack 与 TextField。 Liquid 商品展示示例：遍历 collection.products，输出商品图片、标题、价格与详情链接。
六、最佳实践 API 使用：新开发优先使用 GraphQL 而非 REST；只请求所需字段以降低成本；对大数据集实现分页；批量处理使用批量操作；遵守速率限制（GraphQL 基于成本）。 安全：将 API 凭据存储在环境变量中；验证 webhook 签名；公开应用使用 OAuth；请求最小访问范围；为嵌入式应用实现会话令牌。 性能：适当缓存 API 响应；优化主题中的图片；降低 Liquid 逻辑复杂度；扩展使用异步加载；监控 GraphQL 查询成本。 测试：使用开发商店测试；在不同商店套餐下测试；验证移动端响应式；检查可访问性（键盘、屏幕阅读器）；验证 GDPR 合规。
七、参考文档与脚本 详细指南涵盖应用开发（OAuth、API、webhook、计费）、扩展（Checkout、Admin、POS、Functions）、主题（Liquid、section、部署）。脚本 shopify_init.py 可交互式初始化 Shopify 项目，命令为 python scripts/shopify_init.py。
八、故障排查 速率限制错误：监控 X-Shopify-Shop-Api-Call-Limit 头，实现指数退避，大数据集使用批量操作。 认证失败：验证访问令牌有效性，检查所需范围是否已授予，确保 OAuth 流程完成。 扩展未出现：验证扩展目标正确，检查扩展已发布，确保应用已安装到商店。 Webhook 未接收：验证 webhook URL 可访问，检查签名验证，查看 Partner Dashboard 日志。
九、资源 官方文档：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（Admin → Settings → Apps → Develop apps）、Partner Dashboard（应用管理）、开发商店（免费测试）。 API 版本：季度发布（YYYY-MM 格式），当前为 2025-01，每个版本支持 12 个月，版本更新前需测试。
注：本技能覆盖截至 2025 年 1 月的 Shopify 平台，最新更新请参考官方文档。