环境变量
区分本地绑定、根目录生产变量与部署目标，配置 OAuth、邮件、支付和密钥。
先区分三个位置
Flare 的本地开发与远程部署有不同的配置入口。不要把官网 Next.js 应用的环境变量原样复制过来。
| 位置 | 使用者 | 用途 |
|---|---|---|
apps/web/.dev.vars | Vite / Wrangler 本地运行时 | 本地 APP_URL、认证密钥、可选服务密钥 |
根目录 .env | muse CLI | 部署账户、生产地址、生产认证及集成密钥 |
packages/cli/src/target-resources.ts | 部署资源规划 | Worker、D1、R2、队列与死信队列名称 |
根目录 .env 由 CLI 加载，包括 init 入口；它不会自动成为 Vite 的本地运行时变量，也不会让 init 部署到远程。init 创建或保留本地认证密钥，并执行本地数据库初始化。
首次准备生产配置
在仓库根目录复制示例：
cp .env.example .env填写自己的值，下面只展示变量的形状：
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_API_TOKEN=your-deployment-token
APP_URL=https://app.your-domain.com
AUTH_SECRET=replace-with-a-random-secret-at-least-32-characters
MAIL_FROM=Your Product <[email protected]>
ADMIN_EMAIL=[email protected]CLOUDFLARE_API_TOKEN 仅供管理资源和发布使用，不是应用 API Key。不要加入前端变量、源码片段或浏览器包。AUTH_SECRET 至少 32 个字符；已有生产环境迁移时应保留原值，否则旧会话可能失效。
APP_URL 使用单一 HTTPS origin，不包含路径、查询、片段、账号或端口。未提供时 CLI 可推导 Workers 子域名；自定义域部署应显式填写最终地址，避免认证回调或 Origin 校验使用错误域名。ADMIN_EMAIL 只有在相同邮箱的账号注册并验证后才用于提升管理员，不会自动创建生产账号。
配置按什么顺序生效
CLI 保留进程中已有的变量，因此优先级为：终端或 CI 环境变量、根目录 .env、.muse/<target>.secrets.json 提供的默认值。排查“修改 .env 没有效果”时，先检查终端是否导出了同名变量，不要打印整个环境。
.env、.dev.vars、部署状态及目标生成配置属于本机文件，不能提交。换电脑时通过安全渠道迁移必要的生产输入；仅拉取 Git 不会恢复密钥。
按功能启用服务
| 功能 | 变量 | 同时需要完成 |
|---|---|---|
| Google 登录 | GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET | 控制台授权回调 /api/auth/callback/google |
| GitHub 登录 | GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET | OAuth App 回调 /api/auth/callback/github |
| Turnstile | TURNSTILE_SITE_KEY / TURNSTILE_SECRET | 域名白名单；站点 Key 可公开，Secret 仅服务端 |
| Stripe | STRIPE_SECRET_KEY / STRIPE_WEBHOOK_SECRET | 产品价格映射、签名 Webhook |
| Creem | CREEM_API_KEY / CREEM_WEBHOOK_SECRET | 产品映射与 Webhook |
| Dodo | DODO_API_KEY / DODO_WEBHOOK_SECRET | 环境一致的产品 ID 与 Webhook |
| Waffo | WAFFO_MERCHANT_ID / WAFFO_PRIVATE_KEY | 单行私钥，换行写成 \n；签名与产品配置 |
支付还必须在 packages/config 中启用网关并补齐产品映射，仅填写密钥不会让结账可用。邮件、AI、D1、R2 与 Queues 还依赖 Worker binding，不能用一个 API Key 替代 binding。
检查与排障
pnpm muse:doctor --target production --json
pnpm muse:deploy --target production --plan --json先解决 doctor 的阻断项，再审查 plan 中的目标名称、账户、迁移及创建动作。--plan 不创建资源。
- OAuth 按钮不出现：核对同一 provider 的两个变量是否都设置，并检查
/api/public/auth的公开配置。 - 本地正常、生产登录失败：核对 APP_URL、域名、生产 AUTH_SECRET 和回调 URL。
- 变量似乎没更新：检查进程优先级，并重新启动本地开发服务。
- Workers Builds 找不到变量：在构建环境设置加密变量；远程构建不会读取你电脑上的根目录 .env。