环境变量

了解当前要填哪些配置、写在哪里，以及上线前需要补齐什么。

要接入服务或准备部署时，用这篇查询配置。先使用开发账号体验本地应用，不需要一次填完所有第三方密钥。

开始前准备

完成快速开始。初始化会生成本地文件和签名密钥。用所选应用的 .env.example 查看字段，将真实值写进 .env.local，不要写进示例文件。

阶段	需要配置
第一次本地登录	初始化生成的认证/订阅密钥；本地 D1；seed 账号
替换品牌	默认语言、支持邮箱、本地站点 origin
测试邮件、OAuth、支付或上传	只填当前要测试的功能所需凭据
部署上线	生产 origin、数据库/绑定、稳定签名密钥、真实邮件与所有已启用服务

真实邮件需要 Cloudflare 凭据。即使首页和 seed 登录能用，未配置的服务在使用时仍会失败。产品展示设置在 packages/config/src/index.ts，凭据通过环境变量配置。

配置	Web Cloudflare
本地文件	`apps/web-cloudflare/.env.local`；Worker 预览使用 `.dev.vars`
数据库	D1 绑定 `DB`，不设置 `DATABASE_URL`
对象存储	原生 `R2_BUCKET`，不设置 S3 凭据
邮件	`MAIL_PROVIDER=cloudflare`

pnpm muse:init --yes --app cloudflare
pnpm db:seed:d1
pnpm dev:cf

初始化保留已有值，并生成缺失的签名密钥。不要对已配置环境使用 --force。 CLI 参数是 --app cloudflare，应用目录是 web-cloudflare。

变量	用途
`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 账户域名与密码，不用于创建生产账户

设置 MAIL_PROVIDER=cloudflare、CLOUDFLARE_ACCOUNT_ID 与 CLOUDFLARE_API_TOKEN，验证发件域名。Workers 生产拒绝 resend 和 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。具体沙盒/生产环境取值见各网关文档。

在 apps/web-cloudflare/wrangler.jsonc 声明 D1 DB 与 R2 R2_BUCKET。修改绑定后运行 pnpm cf:typegen。资产通过需要会话的 /files/avatars/* 访问。参见对象存储。

NEXT_PUBLIC_* 会内联进客户端，修改必须重新构建。服务端密钥通过目标平台注入；不要把整个本地环境文件（含 seed、开发 URL）直接当成生产配置。

src/env/readiness.ts 收集错误/警告，生产运行时抛硬错误，构建阶段不因同类硬错误中断。SKIP_ENV_VALIDATION=true 仅用于必要的无密钥 CI 构建，不用于掩盖生产缺失。构建成功不等于认证、邮件、数据库可用。

新增变量同步包级 ./env、所选应用 schema 和 .env.example；两应用差异有意保留。不要提交 .env.local、.dev.vars 或真实密钥。

修改环境文件后重启开发服务。Workers 本地同时更新 .dev.vars，生产配置宿主密钥。打开应用，测试刚启用的功能，例如实际收到邮件或完成沙盒购买。部署环境修改 NEXT_PUBLIC_* 后重新构建。

问题	处理方式
本地配置改了，行为没变	检查所选应用的文件，重启对应服务
Workers 预览与 Next 开发不同	对比 `.dev.vars`、绑定与 `.env.local`，再用 `pnpm cf:preview` 检查
正式链接仍指向 localhost	修改构建时公开 origin，重新构建
生产能启动，但某功能失败	查看服务端/服务商报错，检查该功能必需配置，而不只看构建结果

具体接入步骤见邮件、支付和存储。