参考资料
命令与环境变量
查询 Starter 的 npm 命令、配置分组、功能开关和部署环境优先级。
Starter 使用 npm 锁定依赖。请使用 Node.js >=24.0.1、npm >=11.3.0 和已提交的 package-lock.json。
安装与运行
| 命令 | 行为 |
|---|---|
npm ci | 严格按照锁文件安装依赖图 |
npm run setup | 运行交互式向导，配置本地环境、数据库、认证和可选支付能力 |
npm run dev | 启动 Next.js 开发服务器 |
npm run build | 创建 Next.js 生产构建 |
npm run start | 启动已有的生产构建 |
docker compose up -d | 在本地启动 PostgreSQL 16 和 Mailpit |
docker compose down | 停止本地服务，但不删除具名数据库卷 |
如果本地 5432 端口已被占用，请在运行 setup 时指定主机端口：
VIBEANY_POSTGRES_PORT=55432 npm run setup校验与测试
| 命令 | 行为 |
|---|---|
npm run lint | 对 src/ 下的源文件执行 lint |
npm run typecheck:all | 对整个仓库执行类型检查，包括测试代码 |
npm run validate | 运行当前文档校验、i18n 校验和源码 lint；它不是完整发布门禁 |
npm run preflight | 检查部署环境、已启用能力、数据库可达性、迁移阻塞项和 TypeScript |
npm run --silent preflight -- --json | 输出已脱敏的 JSON 预检报告 |
npm run architecture:check | 运行自动化依赖和仓库边界测试 |
npm test | 以监听模式启动 Vitest |
npm run test:run | 执行一次全部 Vitest 测试 |
npm run test:unit | 执行一次 tests/unit 下的测试 |
npm run test:coverage | 按已配置的覆盖率阈值运行测试 |
npm run e2e | 运行 Playwright 测试套件 |
npm run e2e:smoke | 运行冒烟 E2E 用例 |
npm run e2e:auth | 运行认证 E2E 用例 |
PostgreSQL 集成命令要求显式配置可随时丢弃的测试数据库。已经实现安全检查的测试套件会拒绝不安全的目标。
数据库与产品命令
| 命令 | 行为 |
|---|---|
npm run db:generate | 根据数据库结构变更生成 SQL 迁移和 Drizzle 元数据 |
npm run db:migrate | 通过事务型 app_migrations 执行器运行已提交的 SQL 文件 |
npm run db:push | 始终失败；禁止直接推送数据库结构 |
npm run db:studio | 为当前配置的数据库打开 Drizzle Studio |
npm run rebrand:validate | 检查是否残留 Starter 品牌 |
npm run i18n:validate | 校验语言目录结构和必需消息 |
npm run i18n:coverage | 输出翻译覆盖率报告 |
npm run starter:check | 重大定制或升级后运行 Starter 一致性检查 |
npm run payments:refund:assess -- ... | 生成只读退款政策评估；不会联系服务商或修改数据 |
npm run deploy:vercel | 运行严格关闭支付的 Vercel 基线预检、迁移和生产部署 |
公开的运维路径只需要这里列出的买方可用命令。
环境文件优先级
.env.example是 Starter 支持变量的权威公开清单。- 除非存在权威部署环境，否则本地脚本加载
.env.local。 npm run deploy:vercel默认使用.env.production.local，会移除继承的应用变量，并阻止子命令回退读取.env.local。- 修改 Vercel 环境变量后，只有新构建才会使用新值。
- 所有
NEXT_PUBLIC_*值都会暴露给浏览器代码。切勿把凭据放入其中。
核心应用
| 变量 | 用途 |
|---|---|
DATABASE_URL | Better Auth、Drizzle 和应用持久化使用的 PostgreSQL 连接 |
BETTER_AUTH_SECRET | 会话和认证密钥；预检必需 |
BETTER_AUTH_URL | Better Auth 的规范源地址；本地开发使用可变端口时留空，生产环境必须设置 |
NEXT_PUBLIC_SITE_URL | 元数据和预检使用的公开站点源地址 |
NEXT_PUBLIC_APP_URL | 应用源地址，也是生产认证的后备地址 |
NEXT_PUBLIC_BRAND_NAME | 可选的部署级品牌名称覆盖值 |
NEXT_PUBLIC_BRAND_WORDMARK_ACCENT | 可选的文字标识强调部分覆盖值 |
ADMIN_EMAILS | 用逗号分隔的管理员邮箱允许列表 |
认证、邮件和滥用防护
| 变量 | 用途 |
|---|---|
NEXT_PUBLIC_ENABLE_EMAIL_AUTH | 启用 Better Auth 邮箱密码 UI 和邮件投递 |
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET | 完整的 Google OAuth 服务端凭据对 |
NEXT_PUBLIC_GOOGLE_CLIENT_ID | One Tap 检测使用、浏览器可见的 Google client ID |
NEXT_PUBLIC_ENABLE_ONE_TAP | Google 完整配置存在时启用 Google One Tap |
RESEND_API_KEY, RESEND_FROM_EMAIL | Resend 投递凭据和已验证发件地址 |
SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS | 完整的 SMTP 后备配置 |
NEXT_PUBLIC_TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEY | 注册验证使用的完整 Turnstile key 对 |
生产环境至少必须启用一种完整的认证方式。运行时还支持 Google OAuth 和 SMTP，但受支持的 Vercel 基线使用邮箱密码和 Resend。
支付
| 变量 | 用途 |
|---|---|
NEXT_PUBLIC_ENABLE_PAYMENTS | 控制支付 UI 和支付端点 |
PAYMENTS_PROVIDER | 选择唯一一个当前服务商：stripe 或 creem |
CRON_SECRET | 认证订阅积分定时发放任务 |
PAYMENTS_SUBSCRIPTION_REFUND_MAX_USAGE_PERCENT | 人工审核的用量上限采用严格小于判断，不包含边界；5 表示用量恰好为 5% 时不符合条件 |
STRIPE_SECRET_KEY, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY | Stripe 服务端密钥和浏览器端密钥 |
STRIPE_WEBHOOK_SECRET | /api/payments/webhook 使用的 Stripe 签名密钥 |
STRIPE_PRICE_STARTER_*, STRIPE_PRICE_PRO_* | 月付和年付订阅的规范 Price ID |
STRIPE_PRICE_CREDITS_SMALL, STRIPE_PRICE_CREDITS_MEDIUM, STRIPE_PRICE_CREDITS_LARGE | 页面可见的一次性积分包 Price ID |
STRIPE_PRICE_LANDING_BASIC, STRIPE_PRICE_LANDING_PRO | 可选的一次性产品 Price ID |
CREEM_API_KEY, CREEM_API_BASE | Creem 凭据和测试/生产 API 源地址 |
CREEM_WEBHOOK_SECRET, CREEM_SIGNATURE_HEADER | Creem 签名配置 |
CREEM_PRODUCT_STARTER_*, CREEM_PRODUCT_PRO_* | 月付和年付订阅的 Product ID |
CREEM_PRODUCT_CREDITS_SMALL, CREEM_PRODUCT_CREDITS_MEDIUM, CREEM_PRODUCT_CREDITS_LARGE | 页面可见的积分包 Product ID |
CREEM_PRODUCT_LANDING_BASIC, CREEM_PRODUCT_LANDING_PRO | 可选的一次性 Product ID |
启用支付后，预检只校验所选服务商，但会要求其内置可见产品目录完整。STRIPE_PRICE_STARTER 和 STRIPE_PRICE_PRO 是保留的旧版月付别名；新配置应使用明确的 _MONTHLY 变量。
更改 PAYMENTS_PROVIDER 会改变新的支付结账和 Webhook 流量。已有订阅的取消和客户门户操作仍使用订阅记录中保存的服务商。更改该开关不会迁移现有订阅。
存储与 AI 图片生成
| 变量 | 用途 |
|---|---|
STORAGE_PROVIDER | r2、s3 或 minio |
S3_ENDPOINT, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_BUCKET_NAME | 必需的 S3 兼容凭据组 |
S3_REGION | 可选区域；运行时默认值为 auto |
S3_PUBLIC_URL | 可选的公开或 CDN 基础 URL |
NEXT_PUBLIC_ENABLE_IMAGE_GENERATION | 控制图片页面、导航和 API |
IMAGE_PROVIDER | 可选的显式选择器：fal、modelscope 或 dashscope |
FAL_KEY, MODELSCOPE_API_KEY, DASHSCOPE_API_KEY | 服务商凭据 |
如果没有显式选择图片服务商，运行时会在已配置的服务商中按 Fal、ModelScope、DashScope 的顺序选择。
展示、法律、分析与开发
| 变量 | 用途 |
|---|---|
NEXT_PUBLIC_TERMS_VERSION, NEXT_PUBLIC_PRIVACY_VERSION | 注册流程中展示的法律文档版本 |
NEXT_PUBLIC_GA_ID, NEXT_PUBLIC_CLARITY_ID | 可选分析工具标识符 |
LOG_LEVEL | debug、info、warn 或 error |
NEXT_PUBLIC_SHOW_DEV_WARNINGS | 控制本地开发警告 |
NEXT_PUBLIC_SHOW_PURCHASE_DEBUG, NEXT_PUBLIC_ENABLE_SELF_GRANT, ALLOW_MANUAL_GRANT | 保留或面向展示的开发变量；不是服务端授权控制 |
生产环境应关闭诊断 UI，但不要把这些变量当成授权边界。当前管理员积分调整路由依赖服务端认证和 ADMIN_EMAILS，不会检查 ALLOW_MANUAL_GRANT。旧 Supabase 浏览器变量不属于当前 Better Auth 配置，不应记录为必需配置。
有关更严格的基线环境契约，请参阅部署到 Vercel。