环境变量

模板有五个配置平面。将它们分开能避免最常见的 Cloudflare 部署错误。

配置平面

平面	示例	本地开发	生产环境
Cloudflare 绑定	`DB`、`UPLOADS`	本地 Worker 根据 `wrangler.jsonc` 创建	在 `wrangler.jsonc` 声明并连接 D1/R2 资源
服务端运行时值	Auth、OAuth、Resend、OpenAI、Replicate、Creem	`.env`	`wrangler secret put <NAME>`
非敏感 Worker 变量	`BETTER_AUTH_URL`	`.env`	`wrangler.jsonc` → `vars`
Vite 构建时值	`VITE_CREEM_PRODUCT_*`、`VITE_IS_DEMO`	`.env`	构建/CI 环境；修改后重新构建
Drizzle Kit 远程凭据	Cloudflare 账户、数据库 ID、D1 token	Shell 或 `.env.local`	仅开发/CI 工具使用，不进入应用运行时

DB 与 UPLOADS 是绑定，不是环境变量。运行时代码在请求期间从 cloudflare:workers 读取它们。这个 D1/SQLite 模板中没有 DATABASE_URL。

为什么本地只需 `.env`

@cloudflare/vite-plugin 会为本地 Worker 环境加载变量，Vite 同时通过 import.meta.env 暴露 VITE_*。因此常规 pnpm dev 只需 .env。如果直接运行 wrangler dev，可将 .dev.vars 作为后备。

wrangler deploy 不会上传 .env 或 .dev.vars。生产环境从 wrangler.jsonc 获取绑定与非敏感变量，通过 wrangler secret put 获取服务端密钥，并从执行构建的环境获取 VITE_*。

核心认证配置

变量	要求	说明
`BETTER_AUTH_SECRET`	核心必需	Better Auth 使用的固定随机密钥。通过 `openssl rand -base64 32` 生成。
`BETTER_AUTH_URL`	核心必需	应用规范 origin。本地用 `http://localhost:3000`，生产环境必须与实际部署 origin 完全一致。

安全的本地示例：

BETTER_AUTH_SECRET=generate-a-real-random-value
BETTER_AUTH_URL=http://localhost:3000

生产 wrangler.jsonc 将 URL 保存为非敏感变量：

"vars": {
	"BETTER_AUTH_URL": "https://app.example.com"
}

单独设置密钥：

pnpm wrangler secret put BETTER_AUTH_SECRET

OAuth 服务商

变量	要求	说明
`GITHUB_CLIENT_ID`	功能必需	GitHub OAuth 应用 client ID
`GITHUB_CLIENT_SECRET`	功能必需	GitHub OAuth 应用密钥
`GOOGLE_CLIENT_ID`	功能必需	Google OAuth 应用 client ID
`GOOGLE_CLIENT_SECRET`	功能必需	Google OAuth 应用密钥

每个启用的服务商都要设置一对值。未配置时应删除或隐藏相应 UI 按钮。回调 URL 见身份认证。

邮件与 AI

变量	要求	说明
`RESEND_API_KEY`	功能必需	发送验证、重置密码与联系邮件
`OPENAI_API_KEY`	功能必需	流式对话路由使用的 OpenAI key
`REPLICATE_API_TOKEN`	功能必需	图片、音频和视频路由使用的 Replicate token

生产环境中这些都是 Worker 密钥。功能设置与加固见邮件、AI 对话和 AI 媒体。

Creem 支付

服务端运行时值

变量	要求	说明
`CREEM_API_KEY`	功能必需	创建 Creem Checkout 的 API key
`CREEM_WEBHOOK_SECRET`	功能必需	验证 `creem-signature` 的 HMAC 密钥
`CREEM_SERVER_IDX`	功能必需	Creem 服务环境选择；未设置时模板默认为 `0`

生产环境通过 wrangler secret put 设置这三项，使其只存在于服务端。

构建时产品 ID

变量	要求	说明
`VITE_CREEM_PRODUCT_PRO_MONTHLY`	功能必需	Pro 月付价格的产品 ID
`VITE_CREEM_PRODUCT_PRO_YEARLY`	功能必需	Pro 年付价格的产品 ID
`VITE_CREEM_PRODUCT_LIFETIME`	功能必需	Lifetime 价格的产品 ID

src/config/price-config.ts 读取这些 ID，Vite 会将它们内联进构建。它们不是 Worker 密钥；修改后必须重新构建并部署。详见支付。

应用标志

变量	要求	说明
`VITE_IS_DEMO`	可选	为 `"true"` 时启用 `user-sidebar-config.ts` 中的演示导航行为

和所有 VITE_* 一样，它在客户端构建中可见，绝不能包含密钥。

D1 与 R2 绑定

绑定在 wrangler.jsonc 中声明：

"d1_databases": [
	{
		"binding": "DB",
		"database_name": "soar-tanstack",
		"database_id": "replace-with-your-d1-id",
		"migrations_dir": "drizzle"
	}
],
"r2_buckets": [
	{ "binding": "UPLOADS", "bucket_name": "soar-tanstack-uploads" }
]

应用代码从 cloudflare:workers 导入 env，并在请求期间的工厂/处理器中读取 env.DB 或 env.UPLOADS。不要改成 process.env.DB，也不要在模块顶层求值时捕获绑定。

Drizzle Kit 远程凭据

变量	要求	说明
`CLOUDFLARE_ACCOUNT_ID`	可选工具	远程 D1 所属 Cloudflare 账户
`CLOUDFLARE_DATABASE_ID`	可选工具	远程 D1 数据库 UUID
`CLOUDFLARE_D1_TOKEN`	可选工具	仅限 D1 的 API token

只有通过 d1-http 驱动连接远程 D1 的 Drizzle Kit 命令才会读取这些值。 drizzle.config.ts 会显式加载 .env.local，也可在 shell 中导出。 pnpm db:generate 是离线操作；模板的 pnpm db:migrate 使用 Wrangler，因此应用运行时不需要这些凭据。

设置生产密钥

逐条运行并交互式输入值：

pnpm wrangler secret put BETTER_AUTH_SECRET
pnpm wrangler secret put GITHUB_CLIENT_ID
pnpm wrangler secret put GITHUB_CLIENT_SECRET
pnpm wrangler secret put GOOGLE_CLIENT_ID
pnpm wrangler secret put GOOGLE_CLIENT_SECRET
pnpm wrangler secret put RESEND_API_KEY
pnpm wrangler secret put OPENAI_API_KEY
pnpm wrangler secret put REPLICATE_API_TOKEN
pnpm wrangler secret put CREEM_API_KEY
pnpm wrangler secret put CREEM_WEBHOOK_SECRET
pnpm wrangler secret put CREEM_SERVER_IDX

只设置你计划启用的功能密钥。不要把真实值提交到 .env.example 或 wrangler.jsonc。