> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibestrap.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 环境变量参考

> 脚手架读取的全部 env 变量，作用，以及能不能不填。

脚手架在启动时用 [@t3-oss/env-nextjs](https://env.t3.gg) + Zod 校验环境变量。完整 schema 在
`src/env.ts`——以那个文件为准。本页是它的镜像，按类别组织，方便你一次复制粘贴，搞定 `.env.local`
（和 prod env）。

约定几条：

* **必填**变量缺失或为空时启动报错。
* **可选**变量默认为空字符串，对应模块静默 no-op。
* `NEXT_PUBLIC_*` 变量**会进浏览器**。永远别在里面放 secret。
* CI build 步骤如果不需要真实值（Vercel preview build、Docker bake 等），设
  `SKIP_ENV_VALIDATION=true` 跳过校验。

## Core

App 启动的最小集合。

| 变量 | 必填 | 默认 | 说明 |
| - | - | - | - |
| `NODE_ENV` | 否 | `development` | `development` / `production` / `test`。runtime 自动设。 |
| `DATABASE_PROVIDER` | 否 | `postgres` | 给未来其他驱动留的位。当前仅支持 `postgres`。 |
| `DATABASE_URL` | **是** | — | Postgres 连接串。生产用**池化** URL。 |
| `BETTER_AUTH_SECRET` | **是** | — | session 签名密钥，16+ 字符。生成：`openssl rand -base64 32`。 |
| `BETTER_AUTH_URL` | 否 | — | 部署后 app 的完整 URL（带 scheme）。生产环境 OAuth 回调必填。 |
| `NEXT_PUBLIC_APP_URL` | 否 | `http://localhost:3000` | sitemap、OG 图、OAuth redirect 用。设为 prod URL。 |
| `NEXT_PUBLIC_APP_NAME` | 否 | `Vibestrap` | title、OG metadata、邮件中的显示名。 |
| `ADMIN_EMAILS` | 否 | `''` | 逗号分隔的管理员邮箱。注册时自动提升为 `role: 'admin'`。 |

## OAuth

每个 provider 独立——id + secret 都填启用，留空隐藏。

| 变量 | 必填 | 默认 | 说明 |
| - | - | - | - |
| `GOOGLE_CLIENT_ID` | 否 | `''` | Google OAuth client id。启用「用 Google 登录」。 |
| `GOOGLE_CLIENT_SECRET` | 否 | `''` | Google OAuth secret（仅服务端）。 |
| `NEXT_PUBLIC_GOOGLE_CLIENT_ID` | 否 | `''` | `GOOGLE_CLIENT_ID` 的镜像。客户端 One-Tap 要用。可暴露。 |
| `GITHUB_CLIENT_ID` | 否 | `''` | GitHub OAuth app id。启用「用 GitHub 登录」。 |
| `GITHUB_CLIENT_SECRET` | 否 | `''` | GitHub OAuth secret。 |

## 邮件（Mail）

默认 Resend。`RESEND_API_KEY` 为空时邮件 facade 静默 no-op。

| 变量 | 必填 | 默认 | 说明 |
| - | - | - | - |
| `RESEND_API_KEY` | 否 | `''` | Resend API key（`re_…`）。验证、欢迎、重置密码邮件靠它。 |
| `RESEND_FROM_EMAIL` | 否 | `onboarding@resend.dev` | `From:` 地址。生产环境换成你验证过的域名。 |
| `RESEND_REPLY_TO_EMAIL` | 否 | `''` | 可选 `Reply-To:` header。 |
| `RESEND_AUDIENCE_ID` | 否 | `''` | newsletter 用的 Resend Audience id（`newsletter.provider = 'resend'` 时）。 |

## Newsletter — Beehiiv

只在 `siteConfig.newsletter.provider = 'beehiiv'` 时生效。

| 变量 | 必填 | 默认 | 说明 |
| - | - | - | - |
| `BEEHIIV_API_KEY` | 否 | `''` | Beehiiv v2 API key。 |
| `BEEHIIV_PUBLICATION_ID` | 否 | `''` | publication id（`pub_…`）。 |

## 支付 — Stripe

默认 provider。只有你实际在卖的 `*_PRICE_*` id 才需要填。

| 变量 | 必填 | 默认 | 说明 |
| - | - | - | - |
| `STRIPE_SECRET_KEY` | 是（激活时） | `''` | `sk_test_…` / `sk_live_…`。 |
| `STRIPE_WEBHOOK_SECRET` | 是（激活时） | `''` | Stripe dashboard webhook 配置里的 `whsec_…`。 |
| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | 否 | `''` | `pk_…`。Stripe.js / Elements 用。 |
| `STRIPE_PRICE_VIBESTRAP_PROMO` | 否 | `''` | Vibestrap promo 档（\$49）的 price id。 |
| `STRIPE_PRICE_VIBESTRAP_STANDARD` | 否 | `''` | Vibestrap 标准档（\$99）的 price id。 |
| `STRIPE_PRICE_PRO_MONTHLY` | 否 | `''` | 示例 Pro 月付订阅。 |
| `STRIPE_PRICE_PRO_YEARLY` | 否 | `''` | 示例 Pro 年付订阅。 |

## 支付 — Creem

仅当 `siteConfig.payment.provider = 'creem'` 时生效。

| 变量 | 必填 | 默认 | 说明 |
| - | - | - | - |
| `CREEM_API_KEY` | 是（激活时） | `''` | Creem API key。 |
| `CREEM_WEBHOOK_SECRET` | 是（激活时） | `''` | Webhook 签名密钥。 |
| `CREEM_PRICE_VIBESTRAP_PROMO` | 否 | `''` | promo 档 price id。 |
| `CREEM_PRICE_VIBESTRAP_STANDARD` | 否 | `''` | 标准档 price id。 |

## AI providers

设 `AI_PROVIDER` 切换 provider。`mock` 默认无需 key 也能流式输出假 token，
demo 页面开箱即用。

| 变量 | 必填 | 默认 | 说明 |
| - | - | - | - |
| `AI_PROVIDER` | 否 | `mock` | `mock` / `openrouter` / `openai` / `anthropic` / `replicate` / `fal`。 |
| `OPENROUTER_API_KEY` | 否 | `''` | OpenRouter key（接入大多数 LLM 的网关）。 |
| `OPENROUTER_BASE_URL` | 否 | `https://openrouter.ai/api/v1` | 仅当自托管网关时改。 |
| `OPENAI_API_KEY` | 否 | `''` | OpenAI key（`sk-…`）。 |
| `OPENAI_BASE_URL` | 否 | `https://api.openai.com/v1` | Azure OpenAI 或兼容 endpoint 时改。 |
| `ANTHROPIC_API_KEY` | 否 | `''` | Anthropic key（`sk-ant-…`）。 |
| `ANTHROPIC_BASE_URL` | 否 | `https://api.anthropic.com` | Bedrock / 代理时改。 |
| `REPLICATE_API_TOKEN` | 否 | `''` | Replicate API token，用于图像/音频模型。 |
| `FAL_KEY` | 否 | `''` | fal.ai key，用于快速图像生成。 |

## 存储（S3 / R2）

默认是 stub——需要上传或签名下载时再接上。

| 变量 | 必填 | 默认 | 说明 |
| - | - | - | - |
| `S3_ENDPOINT` | 否 | `''` | endpoint URL。AWS S3、Cloudflare R2、MinIO 都行。 |
| `S3_REGION` | 否 | `''` | bucket region。R2 用 `auto`。 |
| `S3_ACCESS_KEY_ID` | 否 | `''` | access key id。 |
| `S3_SECRET_ACCESS_KEY` | 否 | `''` | secret access key。 |
| `S3_BUCKET` | 否 | `''` | bucket 名。 |
| `S3_PUBLIC_URL` | 否 | `''` | 对外 CDN base URL。 |

## 反 bot — Cloudflare Turnstile

两把 key 都填，启用 Turnstile 在 signup、forgot-password、newsletter 表单。

| 变量 | 必填 | 默认 | 说明 |
| - | - | - | - |
| `TURNSTILE_SECRET_KEY` | 否 | `''` | 服务端校验密钥。 |
| `NEXT_PUBLIC_TURNSTILE_SITE_KEY` | 否 | `''` | 控件公开 site key。 |

## 客服

每次只挂一个，由 `siteConfig.customerService.provider` 决定。每个 widget 自检 env 变量。

| 变量 | 必填 | 默认 | 说明 |
| - | - | - | - |
| `NEXT_PUBLIC_CRISP_WEBSITE_ID` | 否 | `''` | Crisp website id（UUID）。 |
| `NEXT_PUBLIC_TAWK_PROPERTY_ID` | 否 | `''` | tawk.to property id。 |
| `NEXT_PUBLIC_TAWK_WIDGET_ID` | 否 | `''` | tawk.to widget id。 |
| `NEXT_PUBLIC_INTERCOM_APP_ID` | 否 | `''` | Intercom workspace id。 |
| `NEXT_PUBLIC_CHATWOOT_WEBSITE_TOKEN` | 否 | `''` | Chatwoot website token。 |
| `NEXT_PUBLIC_CHATWOOT_BASE_URL` | 否 | `https://app.chatwoot.com` | 自托管 Chatwoot URL。 |

## 联盟（Affiliate）

`siteConfig.affiliate.provider` 选哪个，就填哪个对应的变量。`internal` provider 不需要 env 变量。

| 变量 | 必填 | 默认 | 说明 |
| - | - | - | - |
| `NEXT_PUBLIC_AFFONSO_PROGRAM_ID` | 否 | `''` | Affonso program id。 |
| `NEXT_PUBLIC_REWARDFUL_API_KEY` | 否 | `''` | Rewardful public API key。 |

## 分析（Analytics）

每个脚本仅在自己 env 变量有值时挂载。可任意混搭。

| 变量 | 必填 | 默认 | 说明 |
| - | - | - | - |
| `NEXT_PUBLIC_GOOGLE_ANALYTICS_ID` | 否 | `''` | GA4 measurement id（`G-…`）。 |
| `NEXT_PUBLIC_POSTHOG_KEY` | 否 | `''` | PostHog 项目 key。 |
| `NEXT_PUBLIC_POSTHOG_HOST` | 否 | `https://us.i.posthog.com` | 欧洲用户：`https://eu.i.posthog.com`。 |
| `NEXT_PUBLIC_PLAUSIBLE_DOMAIN` | 否 | `''` | Plausible 站点域名。 |
| `NEXT_PUBLIC_PLAUSIBLE_HOST` | 否 | `https://plausible.io` | 自托管 Plausible URL。 |
| `NEXT_PUBLIC_UMAMI_WEBSITE_ID` | 否 | `''` | Umami website id。 |
| `NEXT_PUBLIC_UMAMI_HOST` | 否 | `https://cloud.umami.is` | 自托管 Umami URL。 |
| `NEXT_PUBLIC_CLARITY_PROJECT_ID` | 否 | `''` | Microsoft Clarity 项目 ID（热图 + session 录屏）。 |

## 搜索引擎站长工具验证

每个变量通过 Next.js `metadata.verification` 在 `<head>` 渲染一个 `<meta>` 标签，
用来在对应站长后台证明所有权。服务端 env 变量（不带 `NEXT_PUBLIC_` 前缀），
留空就不渲染对应标签。

| 变量 | 必填 | 默认 | 说明 |
| - | - | - | - |
| `GOOGLE_SITE_VERIFICATION` | 否 | `''` | Google Search Console —— `google-site-verification` meta 标签的 `content` 值。 |
| `BING_SITE_VERIFICATION` | 否 | `''` | Bing Webmaster Tools —— `msvalidate.01` meta 标签的 `content` 值。 |
| `YANDEX_SITE_VERIFICATION` | 否 | `''` | Yandex Webmaster —— `yandex-verification` meta 标签的 `content` 值。 |

## GitHub 邀请分发

买家流程用它把付费用户加进你的源码私有 repo 当只读 collaborator。完整配置见
[GitHub 邀请分发](/zh/operations/github-invite-delivery)。

| 变量 | 必填 | 默认 | 说明 |
| - | - | - | - |
| `GITHUB_INVITE_TOKEN` | 否 | `''` | 单 repo 的 fine-grained PAT，权限：Metadata:read + Administration:write。空 = 邀请 UI 自动禁用。 |

## 杂项

| 变量 | 必填 | 默认 | 说明 |
| - | - | - | - |
| `NEXT_PUBLIC_DEMO_MODE` | 否 | `false` | 设 `true` 隐藏真实支付 + 认证，显示只读 demo 浮层。 |

## 另见

* [Vercel 部署](/zh/deployment/vercel) —— 生产环境去哪粘。
* [Cloudflare 部署](/zh/deployment/cloudflare) —— 每个 secret 用 `wrangler secret put`。
* [配置](/zh/configuration) —— `siteConfig` 开关决定哪个 provider 读哪些 key。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.