跳转到主要内容
脚手架在启动时用 @t3-oss/env-nextjs + 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否developmentdevelopment / production / test。runtime 自动设。
DATABASE_PROVIDER否postgres给未来其他驱动留的位。v0.1 只有 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:3000sitemap、OG 图、OAuth redirect 用。设为 prod URL。
NEXT_PUBLIC_APP_NAME否vibestraptitle、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否[email protected]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 年付。
STRIPE_PRICE_LIFETIME否''下游应用 Lifetime 档。
STRIPE_PRICE_CREDITS_BASIC否''积分包 basic。
STRIPE_PRICE_CREDITS_STANDARD否''积分包 standard。
STRIPE_PRICE_CREDITS_PREMIUM否''积分包 premium。
STRIPE_PRICE_CREDITS_ENTERPRISE否''积分包 enterprise。

​
支付 — Paddle

仅当 siteConfig.payment.provider = 'paddle' 时生效。
变量必填默认说明
PADDLE_API_KEY是（激活时）''Paddle API key。
PADDLE_WEBHOOK_SECRET是（激活时）''Webhook 签名密钥。
PADDLE_PRICE_VIBESTRAP_PROMO否''promo 档 price id。
PADDLE_PRICE_VIBESTRAP_STANDARD否''标准档 price id。
NEXT_PUBLIC_PADDLE_CLIENT_TOKEN否''Paddle.js 公开 client token。
NEXT_PUBLIC_PADDLE_ENV否sandboxsandbox 或 production。和 API key 对齐。

​
支付 — Lemon Squeezy

仅当 siteConfig.payment.provider = 'lemonsqueezy' 时生效。
变量必填默认说明
LEMON_SQUEEZY_API_KEY是（激活时）''Lemon Squeezy dashboard 的 API key。
LEMON_SQUEEZY_STORE_ID是（激活时）''数字 store id。
LEMON_SQUEEZY_WEBHOOK_SECRET是（激活时）''Webhook 签名密钥。
LEMON_VARIANT_VIBESTRAP_PROMO否''promo 档 variant id。
LEMON_VARIANT_VIBESTRAP_STANDARD否''标准档 variant id。

​
支付 — 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

Phase 2 启用。v0.1 默认 mock provider，demo 页面无 key 也能流式输出假 token。
变量必填默认说明
AI_PROVIDER否mockmock / 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/v1Azure OpenAI 或兼容 endpoint 时改。
ANTHROPIC_API_KEY否''Anthropic key（sk-ant-…）。
ANTHROPIC_BASE_URL否https://api.anthropic.comBedrock / 代理时改。
REPLICATE_API_TOKEN否''Replicate API token，用于图像/音频模型。
FAL_KEY否''fal.ai key，用于快速图像生成。

​
存储（S3 / R2）

v0.1 是 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。
NEXT_PUBLIC_TOLT_API_KEY否''Tolt 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_PUBLIC_YANDEX_METRIKA_ID否''Yandex Metrika counter id（纯数字）。

​
搜索引擎站长工具验证

每个变量通过 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 值。

​
License 派发

购买成功后下载 endpoint 重定向到的地址。
变量必填默认说明
LICENSE_DOWNLOAD_URL否''带 {key} 占位符的 URL 模板。通常是 GitHub 私有 release tarball 或 S3 签名 URL。

​
杂项

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

​
另见

  • Vercel 部署 —— 生产环境去哪粘。
  • Cloudflare 部署 —— 每个 secret 用 wrangler secret put。
  • 配置 —— siteConfig 开关决定哪个 provider 读哪些 key。