SPX 使用指南

SPX 是什么

SPX 是一套可交付的线上站点商品：首页、价格、博客、下载页和会员工作台一体化，内置 Stripe 结账、Supabase 登录、支付 Webhook、事务邮件和购买记录。你看到的这个网站，就是它的真实运行效果。

这份指南按上线顺序组织：本地跑通 → 配置数据库 → 接入支付 → 配置邮件 → 部署上线 → 日常维护。全程大约 30 到 60 分钟。

1. 本地跑通

解压源码包后安装依赖并启动开发服务器：

npm install
npm run dev

打开 http://localhost:3000 看到首页即表示基础环境正常。首次运行不需要任何外部服务，页面会正常渲染，登录和支付等功能需要完成后面的配置。

2. 配置 Supabase

创建项目并执行迁移

• 在 Supabase 创建项目，进入 SQL Editor。
• 依次执行 supabase/migrations/ 下的两个迁移文件，创建 profiles、leads 和 purchases 表。
• 在 Authentication → URL Configuration 中设置 Site URL，并添加 http://localhost:3000/auth/callback 和线上回调地址。
• 开启 Email 登录；如需 Google 登录，在 Provider 中配置 OAuth 凭据。

填写环境变量

复制 .env.example 为.env.local，填入项目 URL 和密钥：

NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=eyJ...
SUPABASE_SECRET_KEY=sb_secret_...

重启开发服务器后，登录即可写入 profiles 表。

3. 配置 Stripe 支付

创建商品与价格

在 Stripe 创建一次性（One-time）价格，把价格 ID 填入config.ts 的stripe.plans 数组。每个商品支持配置downloadUrl、docsUrl 和多平台 downloadPlatforms。

配置 Webhook

本地调试可使用 Stripe CLI，线上则在 Stripe Dashboard 配置 endpoint：

# 本地转发
stripe listen --forward-to localhost:3000/api/webhook/stripe

# 需要订阅的事件
checkout.session.completed
checkout.session.async_payment_succeeded

把打印出的 whsec_... 填入STRIPE_WEBHOOK_SECRET。支付成功后，Webhook 会写入 purchases 购买记录、更新用户权限，并发送订单确认邮件。

收款方式

想让结账页显示微信 / 支付宝，需要在 Stripe Dashboard 中申请并开通对应支付方式；同一价格可通过 currency options 提供人民币定价。

4. 配置事务邮件

邮件能力基于 Mailgun，用于登录链接和支付确认。在.env.local 填入MAILGUN_API_KEY，并在config.ts 的mailgun 段落修改发件人与支持邮箱。建议先用自己的邮箱完成一次注册和一次测试支付，验证两类邮件都能送达。

5. 部署上线

• 代码推送到 GitHub，并在 Vercel 导入仓库。
• 把 .env.local 中的所有变量配置到 Vercel 环境变量（Production / Preview）。
• 绑定自定义域名，并把 Supabase 回调地址更新为新域名。
• 把 Stripe Webhook 指向 https://你的域名/api/webhook/stripe。

# 上线前自检
npm run build       # 本地构建通过
# 结账 → 支付 → 回调 → 工作台显示已购商品
# 收到支付确认邮件

6. 日常维护

• 内容更新：博客文章集中在 app/blog/_assets/content.tsx，按现有结构新增即可。
• 商品调整：价格、描述、下载地址和文档链接都在 config.ts 中维护。
• 购买数据：purchases 表按支付记录幂等写入，手工补录时注意 user_id 与 price_id 必须准确。
• 样式定制：设计令牌集中在 app/apple-style.css，改令牌即可全站换肤。

下一步

跑通整条链路后，优先做三件事：替换成你自己的商品与文案、完成一次真实小额支付验证、检查邮件送达率。之后就可以放心地把站点交给真实用户了。