> ## 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。