初始化项目与首次收款

本指南带你完成产品配置、登录、测试购买和权益验收。保留 Next.js 与 Supabase，先选定一个计费模式和一个收款渠道，再逐步启用其他渠道。

1. 创建配置

安装依赖后，在项目根目录运行向导。

pnpm install
pnpm setup:project

Windows PowerShell 中可使用 pnpm.cmd。向导会询问产品名称、项目标识、站点地址、计费模式、支付渠道和可选副站模式，然后在确认后创建 .env.local。密钥不通过终端收集，请在编辑器中填写生成文件里的空值。

已有 .env.local 时，向导会退出并保留文件。直接编辑现有配置，再执行 pnpm setup:check。不要为了重跑向导删除现有密钥；产品已有用户或订单后，不要随意修改 NEXT_PUBLIC_APP_ID 或计费模式。

自动化环境可以明确传入非敏感选项。

pnpm setup:project --name "My SaaS" --app-id my-saas --mode credits --providers paypal --yes

可选参数包括 --site-url https://your-domain.example 和 --locale cn。主站不填 locale；人民币副站使用 cn，首次测试支付宝时还需要确认沙箱网关。全部参数见 pnpm setup:project --help。向导不会创建远程数据库、注册支付商品或发布网站。

2. 知道去哪里修改

你要修改的内容	配置入口
页头、页脚与通用页面元数据中的产品名称	`.env.local` 的 `NEXT_PUBLIC_APP_NAME`
项目数据隔离标识	`NEXT_PUBLIC_APP_ID`，发布后保持稳定
本地或线上站点地址	`NEXT_PUBLIC_SITE_URL`
计费模式与收款渠道	`NEXT_PUBLIC_PRICING_MODEL`、`NEXT_PUBLIC_PAYMENT_PROVIDERS`
套餐价格、额度、积分包和试用规则	`config/payment.ts`
服务调用消耗	`config/payment.ts` 的 `SERVICE_COSTS`
支付平台商品、Price 或 Plan ID	向导生成的渠道环境变量
登录密钥与项目地址	Supabase 环境变量，OAuth 在 Supabase 后台配置
SEO 描述、社交链接	`config/seo.ts`
Logo、分享图片、营销文案和法律文本	`public/images/`、页面组件、`locales/` 和对应内容文件
联系邮箱与管理员	`NEXT_PUBLIC_CONTACT_EMAIL`、`ADMIN_EMAILS`

名称配置不会全局替换博客、文档、营销文案或邮件发件人。发件人和通知模板仍需按邮件教程检查。环境变量修改后重启本地开发服务；生产的 NEXT_PUBLIC_* 值会在构建时写入前端，需要重新构建部署。修改 .env.local 不会自动同步线上环境。

只配置正在使用的模式

模式	Stripe / Creem 需要的映射	PayPal 需要的映射	支付宝
`credits`	当前所有可见积分包	不需要预建商品	无商品 ID
`subscription_unlimited`	当前订阅套餐的月付、年付	当前订阅套餐的月付、年付 Plan	无商品 ID
`subscription_quota`	当前订阅套餐的月付、年付，加所有积分包	订阅 Plan，积分包无商品 ID	无商品 ID
`lifetime`	当前所有可见买断套餐	不需要预建商品	无商品 ID

检查器读取 config/payment.ts 的实际套餐 key，不会固定假设有几个套餐。页面上可购买的套餐都需要配置对应映射；只想卖部分套餐，应先按支付配置指南调整可见套餐。不要重命名当前固定 key，也不要让平台商品金额、货币和周期与代码配置不一致。

无限订阅启用试用时，当前 PayPal / Creem 的回头客路径会使用各自的 SUB_NOTRIAL_PRO_MONTHLY 映射。缺少时会警告，必须按渠道文档验证已试用用户不会再次获得试用。支付宝没有免费试用，订阅权益来自单次付款，不等同于自动续费。

3. 检查配置

pnpm setup:check
pnpm setup:check --production

默认按 Next.js 开发环境顺序加载，已有进程环境变量优先，然后依次为 .env.development.local、.env.local、.env.development、.env。生产检查使用 .env.production.local、.env.local、.env.production、.env。不要用生产检查的通过结果代替线上环境核对，线上平台可能提供不同变量。

副站覆盖配置的检查方式如下，与项目的 dev:locale 使用同类 dotenv 加载方式。

pnpm exec dotenv -e .env.local.locale -- pnpm setup:check

如需机器可读报告，可加 --json。退出码 0 表示本地必填与格式检查通过，1 表示有配置错误，2 表示命令本身未能执行。警告不会阻止通过，仍应在发布前处理。原有 build 前置检查保持不变，完整检查需要显式运行。

报告只输出变量名、修复建议和文档路径，不输出密钥。空值和 xxx、your_... 等示例值不能通过检查。它会检查启用渠道和当前模式所需的配置，提示隐藏支付按钮、维护模式和错误的公开密钥配置。

本地检查通过，不代表数据库已初始化、密钥有效、OAuth 已配置、Webhook 能到达或支付已经成功。 这些需要完成下面的实际验收。

4. 初始化数据库并完成登录

按源码根目录的 DATABASE_SETUP.md 连接 Supabase，检查并部署 migrations。不要让工具猜测或替你重置数据库。
确认应用的 NEXT_PUBLIC_APP_ID 与已有项目使用的标识一致。全新项目使用自己的唯一标识。
在 Supabase 配置 Site URL 和允许的回调地址；根据需要开启邮件登录或 Google / GitHub OAuth，并配置邮件发送。
运行 pnpm dev:noPay，完成注册、邮件验证（如已启用）、登录、刷新页面和退出。已有 pnpm dev 的 ngrok 集成可继续使用，但它依赖本机配置。
确认登录后用户资料正常，换一个账户看不到前一个账户的账单、积分或订阅。

5. 完成一次测试购买

在选定渠道使用测试环境或沙箱账号。检查器不会发起扣款，也不能判断商品 ID 属于测试还是正式环境。
把代码里的套餐金额、货币、周期与平台商品逐项核对。Stripe 使用 Price ID，Creem 使用 Product ID，PayPal 订阅使用 Plan ID。
为本地应用准备公开 HTTPS 隧道，在渠道后台注册 https://你的公开地址/api/webhooks/渠道名，例如 /api/webhooks/stripe。普通 localhost 地址不能接收平台回调。需要外部返回时同步检查站点地址和认证回调白名单。
确认 NEXT_PUBLIC_PAYMENT_CTA_DISABLED=false、维护模式关闭，从 /pricing 发起购买并完成沙箱支付。
在平台后台确认 Webhook 已投递，在应用里确认订单和权益变化。不能只看浏览器跳转到成功页。
在平台重发同一 Webhook，确认没有重复发放积分或重复创建权益。

根据计费模式检查结果

模式	首次交易后的验收
积分	购买积分入账，调用已配置服务后按服务端价格扣减；余额不足时拒绝付费操作
无限订阅	订阅或试用状态符合规则；验证取消、到期和已试用用户重新购买的行为
配额订阅	订阅额度与周期正确；用量扣减符合规则，另购积分按既有规则记录与消费
买断	买断权益生效，重复回调不会重复创建权益；需要的交付功能独立配置并验收

首次交易完成后，继续按渠道文档验收退款、续费、失败重试和取消。已有 Creem 自动化测试可通过 pnpm test:creem-webhook 执行，它不能替代完整沙箱交易。

6. 准备上线

部署时填入线上站点地址和所选支付环境的完整配置，更新认证回调白名单、Webhook 地址和签名密钥，再重新构建部署。检查营销文案、Logo、法律文本、邮件发件人、管理员名单和联系邮箱。

上线前在真实部署环境重新验证登录和支付回调。保留错误日志与排查入口，但不要记录密码、API 密钥或完整敏感支付载荷。