Tanplate Docs

按 Capability Profile 配置公开变量、Worker secret 与 Cloudflare binding。

Tanplate 只要求当前 Capability Profile 实际使用的环境项。关闭某项能力后，对应变量、secret 和 binding 不应继续留在部署清单中。

配置分层

类型	配置位置	是否可提交	示例
项目意图	`project.manifest.json`	是	品牌、应用、功能、Provider、locale
公开变量	`apps/*/wrangler.jsonc` 的 `vars`	是	`WEB_ORIGIN`、`TURNSTILE_SITE_KEY`
资源 binding	`apps/*/wrangler.jsonc`	是	`DB`、R2、Queue、AI、Rate Limiter
本地 secret	`apps/web/.dev.vars`、`apps/admin/.dev.vars`	否	`BETTER_AUTH_SECRET`
远程 secret	对应 Cloudflare Worker secret	否	OAuth、Resend、Turnstile secret
部署身份	获得授权的部署环境	否	`CLOUDFLARE_API_TOKEN`

不要把 secret 写入 Wrangler vars

OAuth secret、BETTER_AUTH_SECRET、Resend key 和部署 token 只能进入本地 .dev.vars 或远程 Worker secret。仓库的构建门禁会扫描 Git tracked 文件与构建产物。

项目配置

先在 project.manifest.json 选择要部署的应用和功能：

project.manifest.json

{
  "apps": {
    "admin": { "deploy": true },
    "docs": { "deploy": true },
    "web": { "deploy": true }
  },
  "features": {
    "authentication": { "emailAndPassword": false, "enabled": true },
    "projects": { "enabled": true },
    "userAssets": { "enabled": true }
  }
}

修改 Manifest 后运行：

pnpm init:template
pnpm check:template

初始化器会生成公共配置快照，并按 Profile 管理受控的 Worker 名称、公开变量和 binding。它不会创建远程资源，也不会覆盖未知的 Wrangler 配置。

公开变量

条件	应用	名称	用途
Authentication	Web	`BETTER_AUTH_URL`	Better Auth 对外 origin
Authentication 或 Newsletter	Web	`WEB_ORIGIN`	可信站点与确认链接 origin
事务邮件	Web	`AUTH_DELIVERY_ENVIRONMENT`	`local` / `preview` / `production`
Production Authentication	Web	`TURNSTILE_SITE_KEY`	浏览器 Turnstile site key
Newsletter	Web	`RESEND_FROM_EMAIL`	确认邮件发件地址
Analytics	Web	`UMAMI_SCRIPT_URL`、`UMAMI_WEBSITE_ID`	Umami 浏览器适配
Admin	Admin	`ADMIN_EMAILS`	管理员 bootstrap 身份白名单

公开变量不是 secret，但 Preview 与 Production 仍应使用各自的 origin、发件身份和 Provider 标识。

Worker secrets

条件	应用	名称
Authentication 或 Newsletter	Web	`BETTER_AUTH_SECRET`
Admin	Admin	`BETTER_AUTH_SECRET`
Google Social Auth	Web	`GOOGLE_CLIENT_ID`、`GOOGLE_CLIENT_SECRET`
GitHub Social Auth	Web	`GITHUB_CLIENT_ID`、`GITHUB_CLIENT_SECRET`
Production 事务邮件或 Newsletter	Web	`RESEND_API_KEY`
Production Authentication	Web	`TURNSTILE_SECRET_KEY`
Newsletter	Web	`RESEND_WEBHOOK_SECRET`
远程部署	部署环境	`CLOUDFLARE_API_TOKEN`

Web 与 Admin 同时部署且启用 Authentication 时，两个 Worker 必须使用相同的高强度 BETTER_AUTH_SECRET。Social Auth 凭据只配置在 Web，不复制到 Admin。

Cloudflare bindings

能力	Binding
需要关系数据的 Web 功能 / Admin	`DB`
Projects	`PROJECT_ASSETS_BUCKET`
User Assets	`USER_ASSETS_BUCKET`
Cache	`CACHE`
Jobs	`JOBS_QUEUE`、`JOBS_DLQ`
Product AI	`AI`
Production Auth 防滥用	`AUTH_RATE_LIMITER`

Web 与 Admin 同时消费同一模块时，共享目标环境中的 D1 或对应 R2 bucket；Preview 使用隔离资源。Docs Worker 不绑定业务 D1/R2。

本地环境

pnpm init:template 会为当前 Profile 准备受管的本地配置。只在 .dev.vars 中填写需要的 secret，不要提交该文件：

apps/web/.dev.vars

BETTER_AUTH_SECRET=replace-with-a-local-secret

本地 Auth protection 和邮件投递使用确定性 adapter，不会调用远程 Turnstile 或发送真实邮件。

验证环境

验证 Local inventory：

pnpm check:environment

验证 Local 部署清单：

pnpm plan:deployment -- --target local

Preview 或 Production 的 name-only dry-run 还必须声明 Git ref、部署变量和当前 Profile 所需的 secret 名称。完整可执行示例与授权边界见部署网站，各模块的专用要求见 Cloudflare。

环境配置