使用 Gadget 创建 Shopify 嵌入式应用：从连接 Shopify 到 Webhook 与数据同步
文章目录
构建 Shopify 应用时，开发者通常需要自己处理很多基础工作：
- 创建 Shopify 应用。
- 配置 API 权限。
- 处理 OAuth 安装。
- 注册 Webhook。
- 建立数据库。
- 同步历史数据。
- 搭建管理后台。
- 区分开发环境和生产环境。
- 发布应用版本。
Gadget 可以把这些基础工作组合在一起，让开发者直接从一个可运行的全栈项目开始。
本文根据实际演示，介绍如何使用 Gadget 创建一个 Shopify 应用，并完成以下基础配置：
- 创建 Shopify Custom App。
- 连接 Shopify Development Store。
- 配置 Customer 读取权限。
- 创建 Shopify Customer 数据模型。
- 自动订阅客户 Webhook。
- 运行历史客户数据同步。
- 使用 React、Vite 和 Polaris Web Components 构建嵌入式界面。
- 配置 development 和 production 环境。
- 使用 Tunnel 文件管理 Shopify 应用配置。
这份项目本身还没有实现具体的业务功能，它更像一个可以继续开发的 Shopify 嵌入式应用基础模板。
项目使用的技术栈
Gadget 全栈应用平台
Gadget 为项目提供托管的全栈开发环境，包括：
- Node.js 后端。
- PostgreSQL 数据库。
- React 前端。
- Vite 构建工具。
- React Router。
- Background Jobs。
- Elasticsearch。
- Shopify OAuth。
- Shopify Webhook。
- Shopify 历史数据同步。
- 开发环境和生产环境。
开发者不需要先单独购买服务器、配置数据库或编写完整的 OAuth 安装流程。
Shopify 应用连接
Gadget Shopify Connection 负责处理 Shopify 应用的基础连接工作，包括：
- 创建或连接 Shopify 应用。
- 生成应用安装配置。
- 处理 OAuth。
- 创建 Shopify App Tunnel。
- 订阅模型相关 Webhook。
- 将 Shopify 数据同步到 Gadget。
- 连接开发店铺和生产店铺。
React 与 Polaris Web Components
嵌入式管理后台使用 React 构建，前端由 Vite 提供支持。
字幕中的界面使用 Polaris Web Components，因此可以在 Shopify Admin 中呈现更接近 Shopify 原生风格的界面。
选择 Shopify 应用类型
Custom App 与 Public App
创建 Gadget Shopify 应用时，可以选择不同的应用类型。
Custom App 适合：
- 为自己的店铺开发工具。
- 为某一个客户开发专用系统。
- 在内部使用 Shopify API。
- 开发不需要提交 Shopify App Store 的应用。
Public App 适合：
- 面向多个商家发布。
- 提交到 Shopify App Store。
- 让不同商家安装和使用。
- 未来提供公开的应用定价和分发。
当前 Shopify 新建应用应通过 Dev Dashboard 管理。旧版 Legacy Custom App 已不再作为新应用的创建方式。
本教程选择 Custom App
字幕中的演示选择了 Shopify Custom App。
应用名称可以使用：
shopify-connection-demo
如果只是学习和测试，Custom App 更适合快速开始。
如果未来要提交 Shopify App Store，可以在一开始就按照 Public App 的分发和数据审核要求设计应用。
创建 Gadget Shopify 项目
打开 Gadget 应用创建页面
打开：
gadget.new
选择 Shopify 应用类型。
然后选择：
Custom App
输入应用名称并创建项目。
Gadget 会生成一个包含前端、后端、数据库和 Shopify 连接配置的应用项目。
连接 Shopify 组织
选择 Shopify Partner 组织或开发组织。
字幕中的流程会创建：
- 一个 Shopify 开发应用。
- 一个 Shopify 生产应用。
- Gadget development environment。
- Gadget production environment。
- 开发 Tunnel。
- 生产 Tunnel。
开发 Shopify App 会连接到 Gadget development environment。
生产 Shopify App 会连接到 Gadget production environment。
这样可以避免测试数据和正式数据混在一起。
是否立即创建生产应用
Gadget 可以同时创建开发应用和生产应用。
如果目前只想快速测试，也可以先只配置开发应用，之后再创建生产 Shopify App。
如果已经准备好使用完整的开发和发布流程，建议从一开始就区分：
Development
Production
不要让开发应用直接连接生产数据库。
配置 Shopify API 权限
选择 Customer 读取权限
字幕中的项目只选择了客户读取权限：
Customers read access
同时选择 Shopify Customer 数据模型。
这表示应用需要读取 Shopify 客户数据，但并不一定需要修改客户资料。
权限应该遵循最小化原则：
- 只读取需要的数据。
- 不要为了方便申请写入权限。
- 不要提前申请订单、产品或库存权限。
- 后续确实需要时再新增权限。
选择 Shopify Customer 数据模型
选择 Customer 模型后，Gadget 会显示这个模型可以获取的字段。
这些字段通常分为两类：
- Webhook 中会直接提供的字段。
- Webhook 中可能没有，需要通过数据同步获取的字段。
例如，某些客户营销同意数据可能不会出现在每次 Customer Webhook 中，而是需要在同步时补齐。
在创建应用初期，可以先选择真正需要的字段，避免同步不必要的数据。
自动订阅 Customer Webhook
选择 Customer 模型后，Gadget 会自动配置相关 Webhook。
字幕中的 Webhook 包括：
- Customer Created。
- Customer Updated。
- Customer Deleted。
这些 Webhook 用于让 Gadget 数据库随着 Shopify 客户数据变化而更新。
基本流程如下：
Shopify 客户发生变化
→ Shopify 发送 Customer Webhook
→ Gadget 接收 Webhook
→ Gadget 更新 Customer 数据
配置受保护客户数据
为什么需要填写 Protected Customer Data
客户数据属于敏感数据。
如果应用是 Public App，并且准备提交 Shopify App Store，通常需要说明：
- 应用为什么需要客户数据。
- 应用如何使用客户数据。
- 哪些功能依赖客户数据。
- 数据保存在哪里。
- 谁可以访问这些数据。
- 如何处理客户数据删除请求。
字幕中的演示填写了受保护客户数据访问表单，以展示 Public App 的配置方式。
Custom App 的处理方式
如果应用只是 Custom App，可以先在 Shopify Dev Dashboard 中配置 Custom Distribution。
在这种情况下，通常不需要按照 Public App 的审核流程填写完整的受保护客户数据申请表。
不过，Custom App 仍然需要：
- 遵守 Shopify API 使用规则。
- 保护客户数据。
- 使用合理的访问权限。
- 处理客户数据删除和隐私请求。
- 避免将敏感数据暴露给无权限用户。
选择应用用途和数据字段
如果需要提交受保护客户数据表单，应根据应用的真实用途选择：
- App functionality。
- 需要访问的客户字段。
- 数据使用方式。
- 访问这些数据的功能。
不要为了让表单看起来完整，就选择应用实际上不会使用的字段。
安装到 Development Store
选择开发店铺
选择一个 Shopify Development Store 作为测试店铺。
Development Store 适合：
- 测试 Shopify App。
- 测试 OAuth。
- 测试 Webhook。
- 测试 API 权限。
- 测试数据同步。
- 测试嵌入式后台页面。
不要直接在真实店铺中测试尚未完成的应用安装流程。
安装 Shopify 应用
确认权限和应用配置后，安装应用。
Gadget 会处理 Shopify OAuth。
安装成功后，应用会连接到对应的 Gadget development environment。
安装完成后检查：
- Shopify 应用是否显示为已安装。
- Gadget 是否显示连接成功。
- Development Tunnel 是否创建。
- API 权限是否已经授权。
- Customer Webhook 是否已经注册。
查看 Gadget 嵌入式前端
React 前端结构
Gadget 会生成一个 React 前端。
字幕中通过以下路径查看前端入口：
web
└── routes
└── app
└── index.tsx
这个页面就是 Shopify Admin 中打开的嵌入式应用页面。
使用 Polaris Web Components
Gadget 生成的前端使用 Polaris Web Components。
这样做可以让应用界面更接近 Shopify Admin 的设计语言。
开发者可以在这个入口中继续添加：
- 客户列表。
- 订单管理。
- 产品同步状态。
- 数据表格。
- 设置页面。
- 操作按钮。
- 后台报表。
测试热更新
在前端页面中修改一段文字，例如：
Hello Shopify
保存后，Shopify Admin 中的页面会通过 Hot Module Reloading 自动刷新。
这说明开发 Tunnel 和 Vite 开发服务器正在正常工作。
使用 Gadget CLI 进行本地开发
同步项目到本地
Gadget 提供 CLI，可以将项目文件同步到本地。
字幕中提到的命令是：
ggt dev
具体安装方式和命令参数应以当前 Gadget 文档为准。
本地同步后，可以使用：
- Visual Studio Code。
- Cursor。
- Zed。
- Git。
- 本地终端。
- 本地 AI 编程工具。
本地开发的好处
本地开发可以获得：
- Git 版本控制。
- 本地搜索。
- 更完整的代码补全。
- 本地测试工具。
- 自定义脚本。
- 更灵活的调试流程。
Gadget 仍然负责托管数据库和后端，但开发者可以使用自己熟悉的本地工具编写代码。
查看 Shopify Customer 数据模型
打开 Customer 模型
在 Gadget 中打开 Shopify Customer 数据模型。
可以查看：
- 字段结构。
- 数据类型。
- Webhook 字段。
- 仅同步字段。
- CRUD 操作。
- 关系设置。
- 数据记录。
模型中的字段来源主要有两种：
Shopify Webhook 直接携带的字段
以及：
通过数据同步获取的字段
添加非 Webhook 字段
如果应用需要某个 Webhook 中没有直接提供的字段，可以在 Customer 模型中添加非 Webhook 字段。
这些字段不会在每次 Webhook 到达时自动出现，具体获取方式取决于 Gadget 的字段同步设置。
如果应用不需要这些字段，就不要添加。
这样可以减少：
- 不必要的 Shopify API 请求。
- 数据同步时间。
- Gadget 平台用量。
- 数据库中无用字段。
- Webhook 处理压力。
运行 Shopify 数据同步
使用 Sync recent data
进入 Gadget 的安装或 Shopify Connection 页面，点击：
Sync recent data
字幕中的默认行为是同步最近的 10 条父级记录。
对于 Customer 模型来说，结果通常是最多 10 条客户记录。
这个功能适合开发阶段快速获得测试数据。
查看同步后的客户数据
同步完成后，打开 Customer 数据模型的 Data 页面。
确认：
- 客户记录已经出现。
- 客户姓名和邮箱等字段正确。
- 数据更新时间正常。
- Customer Webhook 和数据同步配置正常。
如果只需要少量测试客户，Sync recent data 比全量同步更合适。
同步全部历史数据
如果需要完整历史客户数据，可以使用 Gadget Sync API。
Sync API 可以根据参数：
- 同步指定模型。
- 同步指定时间范围。
- 限制同步父级记录数量。
- 按创建时间或更新时间同步。
- 执行更完整的历史数据导入。
不要在每次开发测试时都同步全部历史数据。
配置 Development 与 Production Tunnel
Development Tunnel
Gadget 会创建一个开发环境 Tunnel，例如：
shopify.app.development.tunnel
这个 Tunnel 对应：
Shopify Development App
→ Gadget Development Environment
当你在 Gadget 界面中修改以下内容时，开发 Tunnel 会反映这些配置：
- API Scopes。
- Webhook。
- Shopify 应用设置。
- 数据模型连接。
- 开发应用配置。
Production Tunnel
生产环境使用另一个 Tunnel，例如：
shopify.app.tunnel
它对应：
Shopify Production App
→ Gadget Production Environment
开发和生产 Tunnel 必须分开管理。
Tunnel 是应用配置来源
在 Gadget Shopify 项目中，Tunnel 文件相当于 Shopify 应用配置的来源。
它记录了：
- 应用配置。
- API 权限。
- Webhook。
- 开发或生产环境关联。
- Shopify 应用连接信息。
不要只在 Shopify Dev Dashboard 中手动修改配置，却不更新项目中的 Tunnel 管理方式，否则开发环境和生产环境可能出现不一致。
从开发环境发布到生产环境
在开发环境完成测试
上线前先在 Development Store 中测试：
- 应用安装。
- OAuth。
- 客户数据权限。
- Customer Webhook。
- 历史数据同步。
- 前端页面。
- API 请求。
- 错误处理。
- 卸载和重新安装。
部署到生产环境
当 Gadget 应用部署到生产环境时，系统会根据生产 Tunnel 将配置发布到 Shopify Production App。
发布流程通常包括：
开发环境测试
→ 部署 Gadget 生产代码
→ 使用生产 Tunnel
→ 发布 Shopify 应用版本
→ 安装到目标生产店铺
如果使用 Shopify CLI 或 CI/CD 流程，部署过程会根据项目配置执行 Shopify 应用发布操作。
生产环境检查
生产发布前确认：
- 生产 Shopify App 已创建。
- 生产 Tunnel 指向正确环境。
- 生产数据库不是开发数据库。
- 生产 API 权限已经确认。
- 生产 Webhook 已注册。
- 前端 URL 使用生产地址。
- 没有把开发密钥写入生产配置。
- 受保护客户数据配置与应用用途一致。
Custom App 和 Public App 的发布区别
Custom App
Custom App 适合单个商家或同一组织内的专用应用。
它通常用于：
- 内部工具。
- 企业内部系统。
- 单店铺管理后台。
- 为特定客户开发的业务系统。
Custom App 的分发范围受到组织和店铺关系限制，不能简单地分享给任意其他商家。
Public App
Public App 面向更广泛的 Shopify 商家。
它需要准备：
- 应用分发配置。
- OAuth 安装流程。
- 隐私政策。
- 客户数据处理说明。
- 受保护客户数据申请。
- 应用审核材料。
- 应用商店页面。
- 支持和卸载流程。
如果计划提交 Shopify App Store，应从项目初期就按照 Public App 的标准设计权限和数据处理方式。
常见问题
为什么 Webhook 已经有数据，还需要数据同步
Webhook 通常只包含事件所需的部分数据，不一定包含模型的全部字段。
如果应用需要历史记录，或者需要补齐 Webhook 没有提供的字段，就需要通过数据同步获取。
Sync recent data 会同步多少记录
字幕中的 Gadget 界面默认同步最近 10 条父级记录。
具体同步范围可能取决于当前模型和 Gadget 版本。
如果需要精确控制数量或时间范围，应使用 Sync API 参数，而不是依赖后台按钮默认值。
为什么 Customer 模型里有些字段为空
可能原因包括：
- 字段没有出现在 Webhook 中。
- 字段被设置为仅同步获取。
- 还没有运行历史数据同步。
- 字段没有添加到 Gadget 模型。
- Shopify API 权限不足。
- 数据同步尚未完成。
是否应该添加全部 Shopify Customer 字段
不建议。
应当根据应用实际功能选择字段。
客户数据越敏感，越需要控制：
- 访问权限。
- 数据保存范围。
- 同步频率。
- 数据删除流程。
- 应用内部使用方式。
总结
这份字幕实际演示的是使用 Gadget 创建 Shopify 嵌入式应用的基础流程。
项目包含：
- Gadget Node.js 后端。
- PostgreSQL 数据库。
- React 和 Vite 前端。
- React Router。
- Polaris Web Components。
- Shopify OAuth。
- Shopify Customer Webhook。
- Shopify 历史数据同步。
- Background Jobs。
- Elasticsearch。
- Development Tunnel。
- Production Tunnel。
完整流程可以概括为：
创建 Gadget Shopify 项目
→ 选择 Custom App
→ 连接 Shopify 组织
→ 创建 Development 和 Production App
→ 选择 API 权限
→ 添加 Customer 数据模型
→ 配置受保护客户数据
→ 安装到 Development Store
→ 接收 Customer Webhook
→ 同步历史客户数据
→ 开发 React 嵌入式后台
→ 测试 Development Tunnel
→ 部署 Production Environment
这个项目完成后，就可以继续开发真正的业务功能，例如客户管理、订单工具、产品管理、库存同步、客户分组和后台数据分析。
使用 Gadget 的好处是，Shopify 应用开发中大量重复的基础工作已经被连接起来。开发者可以把更多时间放在业务逻辑和用户体验上，而不是从零搭建 OAuth、数据库、Webhook 和数据同步系统。
