环境变量说明

两类配置

公开品牌和功能选项在 packages/core/website.ts；数据库地址、认证密钥、第三方服务凭据在环境变量中。不要把服务端密钥放入公开站配置或带有 PUBLIC_ 前缀的变量。

完整字段表、凭据组和诊断命令见 环境变量。新增变量时同步修改 .env.example、apps/api/lib/env.ts 和对应教程。

本地文件

文件	用途
.env	根目录基础值
.env.local	本机开发与完整预览的覆盖值，不提交
.env.staging.local	预发布数据库命令的目标，不提交
.env.production.local	生产数据库命令的目标，不提交

运行时环境解析由 parseEnv() 执行。Google、GitHub 的标识与密钥需要成对填写；Stripe 的四项基础变量必须全部填写或全部留空。关闭支付模块不会让半组错误配置变成有效配置。

两种数据库连接

完整本地预览使用 DATABASE_URL 直连 PostgreSQL。bun dev 的接口通过 Wrangler 本地代理，需要 CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE_CACHED 和 CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE_UNCACHED。

生产接口读取 HYPERDRIVE_CACHED 与 HYPERDRIVE_UNCACHED 资源绑定；数据库迁移仍通过独立的管理连接执行。资源绑定不是普通字符串环境变量。

排查顺序

bun run config:check
bun --env-file .env.staging.local scripts/config-check.ts --target staging
bun --env-file .env.production.local scripts/config-check.ts --target production

后两条需要先准备对应文件中的完整目标环境变量，不会自动读取 Cloudflare 秘密。检查目标、网址格式、认证密钥及第三方凭据是否完整。诊断只检查配置，不连接服务，也不证明真实登录、发信或支付已经成功。修改环境后重启接口；修改构建时公开配置后重建网页。