环境配置

仓库中的 .env.example 是购买者可配置项的事实来源。开发时将它复制为 .env.local，生产环境则在部署平台中配置同名变量。

cp .env.example .env.local

Git 会忽略 .env.local 和其他本地环境文件。绝不要提交这些文件。

公开值与仅服务端值

以 NEXT_PUBLIC_ 开头的变量可能被嵌入浏览器 JavaScript。它们只能用于公开 URL、可发布 ID 和功能开关。

数据库凭据、服务商密钥、Webhook 密钥、SMTP 密码和 BETTER_AUTH_SECRET 必须使用仅服务端变量。绝不要为了让客户端代码读取密钥而给它加上 NEXT_PUBLIC_ 前缀。

核心本地配置

可用的本地邮箱身份认证基线如下：

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/vibeany
BETTER_AUTH_SECRET=<generated-secret>
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_ENABLE_EMAIL_AUTH=true
NEXT_PUBLIC_ENABLE_PAYMENTS=false

请生成身份认证密钥，不要自己编一个容易记住的值：

openssl rand -base64 32

一般的本地开发无需设置 BETTER_AUTH_URL。Better Auth 会跟随实际的 localhost 源地址，包括非默认端口。生产环境应将其设置为规范 HTTPS 源地址；固定预览环境或隧道回调 URL 需要指定源地址时，也应显式设置。

配置分组

URL 与展示

变量	用途
`NEXT_PUBLIC_SITE_URL`	元数据、规范 URL、Sitemap 条目和公开链接。
`NEXT_PUBLIC_APP_URL`	应用回调 URL 和返回 URL 的基准地址。
`BETTER_AUTH_URL`	可选的服务端身份认证规范源地址；仅在无法自动解析时需要。
`NEXT_PUBLIC_BRAND_NAME`	可选的部署专属显示名称覆盖值。
`NEXT_PUBLIC_BRAND_WORDMARK_ACCENT`	可选的文字 Logo 强调后缀。

除非你已经有意设计并测试过跨域部署，否则生产环境的站点、应用和身份认证 URL 应使用同一个源地址。

身份认证与邮件

能力	变量
邮箱和密码	`NEXT_PUBLIC_ENABLE_EMAIL_AUTH`, `BETTER_AUTH_SECRET`
Google OAuth	`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`
Google One Tap	Google 变量，以及 `NEXT_PUBLIC_GOOGLE_CLIENT_ID`, `NEXT_PUBLIC_ENABLE_ONE_TAP`
注册 Turnstile	`NEXT_PUBLIC_TURNSTILE_SITE_KEY`, `TURNSTILE_SECRET_KEY`
Resend	`RESEND_API_KEY`, `RESEND_FROM_EMAIL`
SMTP	`SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, `RESEND_FROM_EMAIL`
管理员允许名单与联系表单收件人	`ADMIN_EMAILS`

Turnstile key 必须成对配置。没有服务端 Google 凭据和公开 client ID 时，不要启用 One Tap。ADMIN_EMAILS 中的每个地址都会同时获得管理员授权，并接收联系表单通知，因此这里只能填写受你控制的管理员账户。

支付

只有在完整配置了一个服务商后，才能设置 NEXT_PUBLIC_ENABLE_PAYMENTS=true。PAYMENTS_PROVIDER 必须严格等于 stripe 或 creem，系统不会隐式回退。

新发起的结账和 Webhook 流量会使用当前选中的服务商。已有订阅会保留自身记录的服务商，并继续用它执行取消订阅和打开客户门户等操作。切换这个开关不会迁移现有订阅。

服务商凭据、Webhook 密钥、产品或价格 ID、CRON_SECRET，以及可配置的订阅退款阈值，都在支付流程文档中说明。所有密钥必须保留在服务端。

可选产品能力

能力	主要变量
AI 图片生成	`NEXT_PUBLIC_ENABLE_IMAGE_GENERATION`、可选的 `IMAGE_PROVIDER`，以及 `FAL_KEY`、`MODELSCOPE_API_KEY`、`DASHSCOPE_API_KEY` 之一
对象存储	`STORAGE_PROVIDER`, `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_BUCKET_NAME`，以及可选的区域/公开 URL
分析	`NEXT_PUBLIC_GA_ID`, `NEXT_PUBLIC_CLARITY_ID`
法律条款确认	`NEXT_PUBLIC_TERMS_VERSION`, `NEXT_PUBLIC_PRIVACY_VERSION`

在对应服务商配置并测试完成前，请保持可选功能关闭。UI 和 API 使用同一组功能开关。

预留的开发变量

环境变量结构中包含用于购买诊断、自助发放、手动发放、详细日志和开发警告的名称。其中一些只是预留项或展示层变量，并未被每条运行时路径使用。特别要注意，ALLOW_MANUAL_GRANT 不是管理员积分调整 API 的授权边界。特权访问由服务端身份认证和 ADMIN_EMAILS 允许名单强制执行。只有当对应的服务端路由和测试都证明某个开关确实生效时，才能把它视为真正的生产控制项。

布尔开关

共享功能开关解析器接受 true、1、on、enabled 和 yes 等值。项目和部署配置中请统一使用小写的 true 或 false，让代码审查结果更明确。

生产环境配置

请在部署平台设置生产值，不要复制 .env.local。生产环境至少需要一个可访问的数据库、强身份认证密钥、非 localhost 的 HTTPS 源地址，以及至少一种经过测试的登录方式。

如果启用了邮箱身份认证，生产环境还需要以下配置之一：

RESEND_API_KEY 和有效的 RESEND_FROM_EMAIL；或
完整的 SMTP host、port、user、password，以及 RESEND_FROM_EMAIL。

配置真实生产 URL 和已启用能力后，运行：

npm run preflight

Preflight 会检查核心变量、已启用服务商、数据库连接、迁移安全性和 TypeScript。当 NEXT_PUBLIC_SITE_URL 仍指向 localhost 时，它会有意失败，因此这是生产就绪检查，不是本地开发健康检查。

如需机器可读、已脱敏的输出：

npm run --silent preflight -- --json

修改后需要重启

Next.js 会在进程启动时读取服务端变量，而公开变量可能在构建期间被嵌入。修改 .env.local 后请重启 npm run dev；修改生产变量后请创建新的部署。

接下来可以阅读身份认证与邮件，或返回快速开始。

本页目录