Shopify 应用开发路线:从 CLI 到上架的工程实践

前言

如果你要做的是店铺后台能力扩展、数据管理或系统对接,那应用开发就是主路线。它要求你理解 OAuth、Admin API、Webhooks 以及 Shopify 的扩展体系,但也带来了最完整的功能边界和商业化能力。

本文面向工程师,给出从脚手架到上线的一条可落地路径。

1. 你在构建什么

Shopify 应用主要分三类:

• Public App:面向所有商家,上架 App Store
• Custom App:只服务单个店铺
• Draft App:开发阶段与测试阶段

核心能力几乎一致,区别在分发方式、审核流程与商业化能力。

2. 推荐技术栈

• CLI:Shopify CLI
• 前端:React + Polaris
• 服务端:Remix/Node.js(官方默认)或 Rails
• 接口:GraphQL Admin API(优先) + Webhooks
• 嵌入:App Bridge

3. 初始化项目与开发环境

使用 Shopify CLI 生成并启动开发服务:

shopify app dev

CLI 会完成 OAuth 基础配置、应用注册与本地开发回调,你可以直接进入业务开发。

4. OAuth 与安装流程

安装流程本质是 OAuth:

1. 生成授权 URL
2. 获取 access token
3. 保存 shop + token
4. 处理卸载 webhook

在 Remix 模板里通常已集成,你需要保证 token 的生命周期管理和安全存储。

5. GraphQL Admin API:推荐的主接口

GraphQL 允许你按需获取字段,减少冗余,并支持批量请求:

query Products($first: Int!) {
  products(first: $first) {
    edges {
      node {
        id
        title
        status
      }
    }
  }
}

Node 侧调用示例:

const query = `
  query Products($first: Int!) {
    products(first: $first) {
      edges { node { id title } }
    }
  }
`;

const res = await client.query({
  data: { query, variables: { first: 10 } },
});

6. Webhooks:让系统事件驱动

常用事件:

• orders/create
• products/update
• app/uninstalled

示例(伪代码):

app.post("/webhooks/orders_create", verifyShopifyHmac, async (req, res) => {
  await syncOrder(req.body);
  res.sendStatus(200);
});

7. Admin 嵌入与 UI 规范

嵌入式应用通常通过 App Bridge 保持会话,UI 使用 Polaris 组件。这样不仅体验一致,也有助于审核通过。

8. App Extensions:把能力放到正确位置

扩展让你的能力出现在 Admin 的资源页面、折扣配置或结账流程中:

shopify app generate extension

扩展配置存放在 shopify.extension.toml,随应用版本一起发布。

9. 上线与审核

公开应用需要审核,审核重点包括:

• 权限最小化
• UX 与一致性
• 数据安全与隐私说明

部署建议选择稳定平台,确保 HTTPS 与日志可追溯性。

10. 常见坑

• GraphQL 速率限制未处理
• Webhook 未做 HMAC 校验
• scopes 申请过度导致审核被拒
• Admin UI 不符合 Polaris 规范

结语

应用开发是 Shopify 生态里能力最强、商业化路径最清晰的路线。建议从 Remix + GraphQL + Webhooks 入手,逐步演进到 Extension 与 Billing。只要把握好鉴权、数据与扩展三条主线,就能持续迭代出可复用的产品能力。