快速搭建内嵌 Shopify 应用的全栈样板，含会话、订阅与 Webhook。

方案简介

本方案是一套用于 Shopify 内嵌应用开发的全栈样板（boilerplate），以 Node.js/Express.js 作为服务端、React.js（经 Vite 构建并配合 raviger 路由）作为客户端、MongoDB（经 mongoose）作为会话与数据库管理层，并使用 Ngrok/Cloudflare 隧道对外暴露 HTTPS 地址。它解决的问题是把 Shopify 应用开发中大量繁琐的样板工作一次做完：认证中间件、会话持久化、周期性订阅变现、Webhook 注册、路由组织以及 GDPR 处理器等。项目明确参考了 Shopify 工程团队官方 starter 模板的设计选择，以保证与官方模板间的平滑过渡。适合希望以简单 clone 后即可开始写业务代码的 Shopify 应用开发者，尤其是熟悉 MERN 技术栈的新手。

亮点与能力

• MongoDB 会话与数据库管理开箱即用
• 周期性订阅（recurring subscriptions）变现方案就绪
• Webhook 已隔离并配置完成
• React 客户端路由已通过 raviger 处理
• 内置 App Proxy 路由示例，可从店铺直接访问应用数据
• GDPR 处理器（数据请求/客户删除/店铺删除）已备好
• 认证中间件全部按 Shopify 官方指南配置
• 内置 inApp 订阅、路由、Webhook 等模板代码

组成与分工

• React.js：客户端框架，配合 raviger 处理路由与导航
• raviger：轻量路由库，用 navigate("/path") 导航，避免 Switch 等样板代码
• Express.js：服务端框架，承载路由、中间件、Webhook 与 App Proxy
• MongoDB / mongoose：会话持久化与数据存储，入门友好
• Vite：构建 React 客户端到 dist/client，提供 dev/build 能力
• Ngrok / Cloudflare Tunnel：把本机端口暴露为 HTTPS 地址，用于回调 URL
• Shopify Polaris：Shopify 官方 UI 组件库
• @shopify/shopify-api：Shopify API 交互与认证
• cryptr：加密会话 token
• Shopify CLI：生成/更新 shopify.app.toml 配置并同步到 Partner Dashboard

前置要求

• Shopify Partner Dashboard 账号，创建一个 Public 或 Custom 应用
• MongoDB（本地可用 mongodb://127.0.0.1:27017/app-name-here）
• Ngrok 账号（或本地安装 cloudflared）
• Windows 用户需先执行：

bash
npm install -g win-node-env

• 安装 Shopify 全局依赖与项目依赖：

bash
npm run g:install
npm i --force

• 不要删除 shopify.app.toml，Shopify CLI 3.0 必需，即使为空。

实施步骤

1. 安装依赖

bash
npm run g:install
npm i --force

2. 在 Partner Dashboard 创建应用

App URL 先填 https://localhost，真实 URL 稍后生成。

3. 配置 .env

按 .env.example 构建，包括 SHOPIFY_API_KEY、SHOPIFY_API_SECRET、SHOPIFY_API_SCOPES、SHOPIFY_APP_URL、MONGO_URL、ENCRYPTION_STRING（用于加密会话 token，丢失则无法解密）、VITE_SHOPIFY_API_KEY 等。

4. 生成隧道 URL

bash
npm run ngrok

或：

bash
npm run cloudflare

把生成的 https:// 填入 SHOPIFY_APP_URL 与 Partner Dashboard。

5. 同步配置到 Shopify

bash
npm run update:config

切勿手改 toml 文件，用环境变量代替。

6. 构建并启动

开发模式 npm run dev；生产模式先 npm run build（Vite 编译到 dist/client）再 npm run start。

注意事项与常见问题

• 依赖安装使用 --force，因追求最新版本会有兼容性问题，但暂无功能影响；遇到问题可开 issue。
• ENCRYPTION_STRING 丢失将无法解密会话，务必妥善保存。
• 不可手改 toml 文件，一切通过 env 配置。
• GitHub Codespaces 上 MongoDB 需要 root 权限：sudo mongod --dbpath mongo/。
• 数据与会话存储刻意保持极简，方便按需自定义模型。
• npm run update 依赖 npm-check-updates 强制升级，可能破坏功能。
• 订阅 returnUrl 不建议拼 admin URL，因 Shopify 正迁移到 admin.shopify.com，重新走 auth 由 Shopify 处理跳转更稳妥。

优缺点

• ✓ 会话与订阅开箱即用
• ✓ 贴近官方模板易迁移
• ✕ 依赖需 --force 安装
• ✕ 存储保持极简需自行扩展

出处

本方案挖掘自开源项目 kinngh/shopify-node-express-mongodb-app，方案内容与实施命令均来自其 README 原文。