环境变量
为 Next.js 模板配置环境变量并连接服务。
配置位于 .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 媒体。 |
站点与演示
| 变量 | 必需性 | 说明 |
|---|---|---|
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_*的更改需要重新构建。参见 部署。