Shopify App 开发完整指南

Shopify App 是扩展 Shopify 平台能力的标准方式——可以是 Shopify App Store 上架的公开应用、单店专用的 Custom App、或服务于内部业务的私有集成。Shopify 自 2021 年起对 App 开发架构做了多次重大调整（Online Store 2.0、Checkout Extensibility、Theme App Extensions），现在的 App 开发与早期完全不同。

本文是 App 开发的体系性入门。深度技术内容（API、Webhook、Functions）见各对应专题文章。

若你在 Cursor / Claude Code / VS Code 等用 AI 辅助开发，推荐启用 Shopify AI Toolkit ，本站导读：Shopify AI Toolkit 使用指南。

一、App 类型选择

三种主要类型

类型	分发方式	审核	适用
Public App	Shopify App Store	必须	面向所有商家
Custom App	单店私有	否	单一商家深度定制
Private App（已废弃）	单店 API key	否	已不推荐，逐步淘汰

Public App 的两个亚类

Listed：在 App Store 公开展示
Unlisted：通过私有链接安装（如内部工具、企业客户专用）

选型决策

你的 App 是给：
   ↓
单一商家 + 内部业务（不上架）
   → Custom App
   ↓
多个客户 + 内部分发（合作伙伴）
   → Unlisted Public App
   ↓
开放给所有 Shopify 商家
   → Listed Public App（需 App Store 审核）

商业模型差异

模型	Custom App	Public App
收入	按项目报价	月费 / 一次性 / 免费
客户关系	直接合同	Shopify 居间
维护	客户付费	月度订阅持续支持
Shopify 抽成	0	0-20%

二、开发环境搭建

Shopify CLI 安装

npm install -g @shopify/cli @shopify/app

初始化项目

shopify app init my-app
# 选择模板：
#   - Remix（推荐，Shopify 官方默认）
#   - Node + Vite + React
#   - 仅扩展（无后端）

项目结构（Remix 模板）

my-app/
├── app/                       # Remix 路由 + 业务逻辑
│   ├── routes/
│   ├── shopify.server.ts     # Shopify 连接配置
│   └── db.server.ts          # 数据库
├── extensions/                # App Extensions
│   ├── theme-extension/      # 主题扩展
│   ├── checkout-extension/   # 结账扩展
│   ├── admin-extension/      # Admin UI 扩展
│   └── function/             # Shopify Functions
├── prisma/                    # 数据库 schema
├── shopify.app.toml          # App 配置
└── package.json

本地开发

# 启动开发服务
shopify app dev
 
# 自动完成：
# - 创建临时 dev s...