---
url: /docs/getting-started/environment-variables.md
---
# 环境变量说明

## 两类配置

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

完整字段表、凭据组和诊断命令见 [环境变量](../agentbuff-stack/env.md)。新增变量时同步修改 `.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` 资源绑定；数据库迁移仍通过独立的管理连接执行。资源绑定不是普通字符串环境变量。

## 排查顺序

```sh
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 秘密。检查目标、网址格式、认证密钥及第三方凭据是否完整。诊断只检查配置，不连接服务，也不证明真实登录、发信或支付已经成功。修改环境后重启接口；修改构建时公开配置后重建网页。