环境变量
为 Next.js 模板配置环境变量并连接服务。
架构说明： 本页的 Web 配置适用于独立产品。作为 Unified Platform Host 时，还需应用服务端配置中的原生 Origin、OAuth audience、App API、Webhook、存储和通知边界。
配置位于 .env（由 .env.example 复制而来）。本页是模板读取的每一个变量的参考，
按服务分组。每个变量都会标注：
- 必需（核心） —— 缺少则应用无法启动或核心认证失效。
- 必需（功能） —— 仅在使用该功能时需要。
- 可选 —— 有默认值或仅改变行为。
服务端密钥 vs. 公开值。 以 NEXT_PUBLIC_ 为前缀的变量会在构建时内联进
浏览器包，对用户可见 —— 切勿把密钥放在这里。其余变量都是服务端专用。由于
NEXT_PUBLIC_* 的值在构建时固定，修改它们需要重新构建。
核心
| 变量 | 必需性 | 说明 |
|---|---|---|
DATABASE_URL | 必需（核心） | PostgreSQL 连接字符串，例如 postgresql://user:password@localhost:5432/soar_next。 |
Better Auth
| 变量 | 必需性 | 说明 |
|---|---|---|
BETTER_AUTH_SECRET | 必需（核心） | 用于签名会话的密钥。可用 openssl rand -base64 32 生成。保持稳定；更改会使会话失效。 |
BETTER_AUTH_URL | 必需（核心） | 应用的基础 URL。本地为 http://localhost:3000；生产为你的规范 HTTPS URL。 |
Better Auth 会自动从环境读取这些值 —— 它们并不在 src/lib/auth.ts 中通过
process.env 传入。参见 身份认证。
OAuth 提供方
两个提供方都是可选的。若未配置某个，请隐藏其按钮，而不要留下无法工作的控件 —— 见 身份认证。
| 变量 | 必需性 | 说明 |
|---|---|---|
GITHUB_CLIENT_ID | 必需（功能） | GitHub OAuth 应用的 client ID。 |
GITHUB_CLIENT_SECRET | 必需（功能） | GitHub OAuth 应用的密钥。 |
GOOGLE_CLIENT_ID | 必需（功能） | Google OAuth client ID。 |
GOOGLE_CLIENT_SECRET | 必需（功能） | Google OAuth client secret。 |
Creem 支付
| 变量 | 必需性 | 说明 |
|---|---|---|
CREEM_SERVER_IDX | 可选 | 选择 Creem 服务器（沙箱 vs. 正式）。未设置时默认为 0（src/lib/payment/creem.ts）。 |
CREEM_API_KEY | 必需（功能） | 用于创建结账的 Creem API key。 |
CREEM_WEBHOOK_SECRET | 必需（功能） | 校验传入 webhook 签名。 |
NEXT_PUBLIC_CREEM_PRODUCT_PRO_MONTHLY | 必需（功能） | Pro 月付方案的公开 Creem 产品 ID。构建时固定，暴露给浏览器。 |
NEXT_PUBLIC_CREEM_PRODUCT_PRO_YEARLY | 必需（功能） | Pro 年付方案的公开 Creem 产品 ID。 |
NEXT_PUBLIC_CREEM_PRODUCT_LIFETIME | 必需（功能） | 终身方案的公开 Creem 产品 ID。 |
它们将 Free / Pro / Lifetime 定价方案映射到 Creem 产品；与
src/config/price-config.ts 中的展示价格不同。参见 支付。
Resend 邮件
| 变量 | 必需性 | 说明 |
|---|---|---|
RESEND_API_KEY | 必需（功能） | Resend API key。邮箱验证、密码重置与联系表单都需要。缺少它会导致邮箱验证阻止登录。 |
发件人与支持邮箱在 src/config/website-config.ts 中设置（fromEmail、
supportEmail），而非通过环境变量。参见 邮件。
OpenAI（AI 聊天）
| 变量 | 必需性 | 说明 |
|---|---|---|
OPENAI_API_KEY | 必需（功能） | 由流式聊天路由使用。OpenAI SDK 会自动从环境读取。参见 AI 聊天。 |
Replicate（AI 媒体）
| 变量 | 必需性 | 说明 |
|---|---|---|
REPLICATE_API_TOKEN | 必需（功能） | 由图像/视频/音频生成路由使用。Replicate SDK 会自动读取。参见 AI 媒体。 |
原生与移动客户端
仅当原生客户端（如 Unified Mode 下的 SoarStarter Swift 模板）连接本后端时 需要——参见原生认证。
| 变量 | 必需性 | 说明 |
|---|---|---|
APP_SCHEME | 必需（功能） | 你的 App URL scheme（如 soar://）。原生客户端把它作为 Origin 发送；生产环境唯一额外信任的 Origin。 |
DEV_TRUSTED_ORIGINS | 可选 | 逗号分隔的额外受信任 Origin，仅开发环境生效。 |
GOOGLE_IOS_CLIENT_ID | 必需（功能） | 作为 ID Token audience 接受的 Google iOS 客户端 ID。 |
GOOGLE_ANDROID_CLIENT_ID | 必需（功能） | 作为 ID Token audience 接受的 Google Android 客户端 ID。 |
APPLE_APP_BUNDLE_IDENTIFIER | 必需（功能） | iOS Bundle ID。注册原生 Apple 登录并校验 ID Token 的 audience。无需 Services ID 或 client secret。 |
RevenueCat（App Store 购买）
把 App Store 购买同步到共享订阅记录——参见 跨端订阅。
| 变量 | 必需性 | 说明 |
|---|---|---|
REVENUECAT_WEBHOOK_AUTHORIZATION | 必需（功能） | Webhook 必须收到的完整 Authorization header 值（如 Bearer rc_whsec…）。在 RevenueCat 控制台配置完全一致的值。 |
REVENUECAT_PRODUCT_PRO_MONTHLY | 必需（功能） | 映射到 Pro 月付套餐的 App Store 产品 ID。 |
REVENUECAT_PRODUCT_PRO_YEARLY | 必需（功能） | 映射到 Pro 年付套餐的 App Store 产品 ID。 |
REVENUECAT_PRODUCT_LIFETIME | 必需（功能） | 映射到 Lifetime 套餐的 App Store 产品 ID。 |
App API 与对象存储
参见对象存储与直传上传。
| 变量 | 必需性 | 说明 |
|---|---|---|
SOAR_APP_BASE_URL | 可选 | 本应用的公开基址；开发环境用于构建本地上传 URL。默认适配 http://localhost:3000。 |
STORAGE_PROVIDER | 必需（核心） | local（仅开发——生产环境拒绝）或 r2。 |
R2_ACCOUNT_ID | 必需（功能） | Cloudflare 账户 ID（STORAGE_PROVIDER=r2 时）。 |
R2_ACCESS_KEY_ID | 必需（功能） | R2 API Token 的 Key ID。 |
R2_SECRET_ACCESS_KEY | 必需（功能） | R2 API Token 的 Secret。 |
R2_BUCKET | 必需（功能） | 上传使用的 Bucket 名称。 |
R2_PUBLIC_BASE_URL | 必需（功能） | 用于构建对象 URL 的公开基址（自定义域名或 r2.dev）。 |
APNs（推送通知）
由已鉴权的测试推送端点使用——参见推送通知。 均为服务端专属机密。
| 变量 | 必需性 | 说明 |
|---|---|---|
APNS_TEAM_ID | 必需（功能） | Apple Developer 团队 ID。 |
APNS_KEY_ID | 必需（功能） | APNs Auth Key（.p8）的 Key ID。 |
APNS_BUNDLE_ID | 必需（功能） | App Bundle ID，作为 apns-topic 发送。 |
APNS_PRIVATE_KEY | 必需（功能） | .p8 密钥内容；支持 \n 转义，可放在一行。 |
站点与演示
| 变量 | 必需性 | 说明 |
|---|---|---|
NEXT_PUBLIC_SITE_URL | 可选 | 用于 src/app/[locale]/layout.tsx 与营销页中 metadataBase 的规范站点 URL。未设置时回退到 https://soarstarter.com。公开，构建时固定。 |
NEXT_PUBLIC_IS_DEMO | 可选 | 为 "true" 时，切换仪表盘侧边栏的演示行为（src/config/user-sidebar-config.ts）。公开，构建时固定。 |
NEXT_PUBLIC_SITE_URL 与 NEXT_PUBLIC_IS_DEMO 都会被应用读取，但不在
.env.example 中 —— 需自行添加。生产环境请将 NEXT_PUBLIC_SITE_URL 设为你的真实
域名，以便 Open Graph 与规范元数据正确解析；否则会回退到 SoarStarter 默认值。
NEXT_PUBLIC_IS_DEMO 保持未设置（或设为 "true" 以外的任何值）即为正常行为。
本地 vs. 生产
- 本地：
BETTER_AUTH_URL=http://localhost:3000、本地或开发数据库，以及指向 沙箱的CREEM_SERVER_IDX。 - 生产： 你的规范 HTTPS
BETTER_AUTH_URL与NEXT_PUBLIC_SITE_URL、带连接池的 托管数据库、正式的 Creem 服务器与产品 ID、已验证的 Resend 域名，以及全新的BETTER_AUTH_SECRET。注意NEXT_PUBLIC_*的更改需要重新构建。参见 部署。