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

# 配置

> 如何通过 src/config/site.ts 和环境变量层定制 Vibestrap。

Vibestrap 把配置分成三层，每一层有清楚的职责。知道改哪一层，能省你大量时间。

## 三层配置

| 层            | 文件                                      | 控制什么                                      |
| ------------ | --------------------------------------- | ----------------------------------------- |
| **品牌与业务配置**  | `src/config/site.ts`                    | 产品名、定价、套餐、provider 启用开关、社交链接——所有买家会想改的东西。 |
| **密钥与运行时配置** | `.env.local`（由 `src/env.ts` 校验）         | API key、数据库 URL、签名密钥——任何随环境变化的东西。         |
| **面向用户的文案**  | `messages/en.json` + `messages/zh.json` | 用户看到的每一个字符串。双语；两个文件 key 必须对齐。             |

如果你发现自己在改组件源代码来修改文案，停下——
你应该改的是 `messages/{en,zh}.json`。

## `siteConfig` 控制什么

整个文件大约 250 行。下面是几个关键字段：

```ts theme={null}
siteConfig.name            // 品牌名，用于 <title> + 邮件 + footer
siteConfig.url             // 规范 URL —— 驱动 sitemap、OG、邮件链接
siteConfig.shortDescription // hero 副标题、OG 图
siteConfig.product         // 定价卡：标准价 / 促销，按 provider 的 price ID
siteConfig.payment.provider // 'stripe' | 'creem' | 'nowpayments'
siteConfig.customerService  // { enable, provider: 'crisp' | 'tawk' | … }
siteConfig.affiliate        // { enable, provider, internalCommissionPct }
siteConfig.newsletter       // { enable, provider: 'resend' | 'beehiiv' }
siteConfig.analytics        // { vercel, googleAnalytics, posthog, plausible, umami }
siteConfig.credits          // 账本配置：registerGift、monthlyFree…
siteConfig.demoPlans        // 4 档样板（一次性 + 月付 + 年付）
siteConfig.i18n             // locale 与默认 locale
siteConfig.features         // 功能开关（blog / newsletter / OAuth 等）
```

每个字段都有内联注释——通读一遍，不用 grep 你就知道哪些能改。

## `siteConfig` 之外

这些有自己的家——这是有意为之的。

| 关注点                 | 位置                                                 |
| ------------------- | -------------------------------------------------- |
| 环境变量 / 密钥           | `.env.local`，由 `src/env.ts` 校验                     |
| 数据库 schema          | `src/db/{auth,app,affiliate,ai,license}.schema.ts` |
| AI Provider 列表 / 价格 | `src/ai/index.ts` + `src/ai/pricing.ts`            |
| 营销文案                | `messages/{en,zh}.json`                            |
| 邮件模板                | `src/mail/templates/`                              |
| 主题 token            | `src/app/globals.css`（`@theme` 块）                  |
| `/docs` 侧边栏导航       | `src/config/docs-nav.ts`                           |

## 添加一个新功能开关

1. 加到 `siteConfig.features`：

   ```ts theme={null}
   features: { ..., enableMyFeature: true }
   ```

2. 在代码里使用：

   ```tsx theme={null}
   import { siteConfig } from '@/config/site';
   if (siteConfig.features.enableMyFeature) { ... }
   ```

完事——不需要其它管道工作。

## 添加一个 env 变量

1. 在 `src/env.ts` 加一个 Zod 校验项（密钥放 server section；带 `NEXT_PUBLIC_`
   前缀、可安全发到浏览器的放 client section）。
2. 如果是 public 变量，还要加到 `experimental__runtimeEnv`（Next.js 要求）。
3. 在[环境变量参考](/zh/env-reference)里写一笔说明。
4. 用 `import { env } from '@/env'` 读取——不要直接 `process.env.X`。

## 最佳实践清单

* ✅ 品牌改动只动 `siteConfig` 和 `messages/`，不改组件源码。
* ✅ 密钥只在 `.env.local`。`.env.example` 描述结构；真正的 `.env.local` 已被 gitignore。
* ✅ 切换 provider（Stripe → Creem）时，改 `siteConfig.payment.provider` 并设对应的
  `*_PRICE_*` env。代码其他地方不需要关心当前是哪个 provider。
* ✅ `messages/en.json` 与 `messages/zh.json` 永远 key 对齐。
  `node scripts/check-i18n.mjs` 会强制校验。