环境变量
了解当前要填哪些配置、写在哪里，以及上线前需要补齐什么。
要接入服务或准备部署时，用这篇查询配置。先使用开发账号体验本地应用，不需要一次填完所有第三方密钥。
开始前准备
完成 快速开始。初始化会生成本地文件和签名密钥。用所选应用的 .env.example 查看字段，将真实值写进 .env.local，不要写进示例文件。
现在需要配置什么
| 阶段 | 需要配置 |
|---|---|
| 第一次本地登录 | 初始化生成的认证/订阅密钥；开发 Postgres；seed 账号 |
| 替换品牌 | 默认语言、支持邮箱、本地站点 origin |
| 测试邮件、OAuth、支付或上传 | 只填当前要测试的功能所需凭据 |
| 部署上线 | 生产 origin、数据库/绑定、稳定签名密钥、真实邮件与所有已启用服务 |
本地 console 邮件不会真实投递。即使首页和 seed 登录能用，未配置的服务在使用时仍会失败。产品展示设置在 packages/config/src/index.ts，凭据通过环境变量配置。
应用环境
| 配置 | Web |
|---|---|
| 本地文件 | apps/web/.env.local |
| 数据库 | DATABASE_URL，Postgres 连接池 |
| 对象存储 | S3 兼容 S3_* 凭据 |
| 邮件 | resend 或 cloudflare，本地可用 console |
pnpm muse:init --yes --app web --database-url <postgres-url>
pnpm db:seed
pnpm dev初始化保留已有值，并生成缺失的签名密钥。不要对已配置环境使用 --force。
核心变量
| 变量 | 用途 |
|---|---|
NEXT_PUBLIC_SITE_URL | 站点 origin、链接和 OAuth 回调；生产用真实 HTTPS 域名 |
NEXT_PUBLIC_DEFAULT_LOCALE | 默认 en 或 zh |
NEXT_PUBLIC_EMAIL_SUPPORT | 公开支持邮箱 |
BETTER_AUTH_SECRET | 会话签名；生产运行时缺失为硬错误 |
BETTER_AUTH_TRUSTED_ORIGINS | 额外信任 origin，逗号分隔 |
BETTER_AUTH_ENABLE_TEST_UTILS | 自动化测试辅助；正常运行保持 false |
GITHUB_CLIENT_ID/SECRET、GOOGLE_CLIENT_ID/SECRET | 可选 OAuth，缺失时隐藏对应 provider |
NEXT_PUBLIC_GOOGLE_ONE_TAP_CLIENT_ID | 可选 Google One Tap |
NEXT_PUBLIC_TURNSTILE_SITE_KEY、TURNSTILE_SECRET_KEY | 两项都配置才启用验证码 |
MAIL_FROM、MAIL_FROM_NEWSLETTER、CONTACT_FORM_TO | 事务邮件、订阅邮件发件人和联系表单收件人 |
NEWSLETTER_TOKEN_SECRET | 退订链接 HMAC 签名，无认证密钥回退 |
MUSE_SEED_EMAIL、MUSE_SEED_PASSWORD | 本地 seed 账户域名与密码，不用于创建生产账户 |
邮件凭据
Resend 需要 MAIL_PROVIDER=resend 与 RESEND_API_KEY。Cloudflare Email Sending 需要账号 ID、API Token 和已验证发件域名。本地 console 仅打印邮件，生产拒绝它。缺少凭据可能只产生启动警告，但仍会导致验证码无法投递。
计费
默认网关是 BILLING_DEFAULT_GATEWAY（muse_creem、muse_stripe、muse_dodo、muse_waffo）；留空按已配置网关回退。密钥不放到 NEXT_PUBLIC_*。
- Creem：
CREEM_API_KEY、CREEM_WEBHOOK_SECRET、CREEM_ENVIRONMENT - Stripe：
STRIPE_SECRET_KEY、STRIPE_WEBHOOK_SECRET - Dodo：
DODO_PAYMENTS_API_KEY、DODO_PAYMENTS_WEBHOOK_SECRET、DODO_PAYMENTS_ENVIRONMENT - Waffo：
WAFFO_MERCHANT_ID、WAFFO_PRIVATE_KEY、WAFFO_ENVIRONMENT；可选WAFFO_DEBUG、WAFFO_CUSTOMER_PORTAL_URL - 产品：
<GATEWAY>_PRODUCT_ID_PRO_MONTHLY、<GATEWAY>_PRODUCT_ID_PRO_YEARLY、<GATEWAY>_PRODUCT_ID_LIFETIME，前缀为CREEM、STRIPE、DODO或WAFFO
Waffo 私钥在文件里写成一行，用 \n 表示换行。商户私钥用于 API 请求签名；Webhook 使用 SDK 验签，不另设 Waffo webhook secret。具体沙盒/生产环境取值见各网关文档。
对象存储
设置 S3_ENDPOINT、S3_ACCESS_KEY_ID、S3_SECRET_ACCESS_KEY。可选配置包括 S3_AVATARS_BUCKET、S3_AVATARS_PROXY_URL 和 S3_REGION。参见 对象存储。
构建与运行边界
NEXT_PUBLIC_* 会内联进客户端，修改必须重新构建。服务端密钥通过目标平台注入；不要把整个本地环境文件（含 seed、开发 URL）直接当成生产配置。
src/env/readiness.ts 收集错误/警告，生产运行时抛硬错误，构建阶段不因同类硬错误中断。SKIP_ENV_VALIDATION=true 仅用于必要的无密钥 CI 构建，不用于掩盖生产缺失。构建成功不等于认证、邮件、数据库可用。
新增变量同步包级 ./env、所选应用 schema 和 .env.example；两应用差异有意保留。不要提交 .env.local 或真实密钥。
确认结果
修改环境文件后重启开发服务。生产配置宿主密钥。打开应用，测试刚启用的功能，例如实际收到邮件或完成沙盒购买。部署环境修改 NEXT_PUBLIC_* 后重新构建。
常见问题
| 问题 | 处理方式 |
|---|---|
| 本地配置改了，行为没变 | 检查所选应用的文件，重启对应服务 |
| 正式链接仍指向 localhost | 修改构建时公开 origin，重新构建 |
| 生产能启动，但某功能失败 | 查看服务端/服务商报错，检查该功能必需配置，而不只看构建结果 |