配置体系

快速开始：4 个变量启动项目

01MVP 本地开发优先使用产品级 env，从产品自己的 .env.example 复制并修改：

cp products/01mvp/packages/config/.env.example products/01mvp/packages/config/.env

根目录 packages/config/.env 是共享兜底。只有多个产品确实要共用同一批默认值时，再复制它：

cp packages/config/.env.example packages/config/.env

本地开发至少需要下面 4 个变量：

postgresql://localhost:5432/myapp_dev

openssl rand -base64 32

http://localhost:7001        # 开发环境
https://your-domain.com     # 生产环境

http://localhost:7001/api
https://your-domain.com/api

配置系统说明

共享环境变量 schema 位于 packages/config/src/server/env.ts 和 packages/config/src/web/env.isomorphic.ts。产品代码通过自己的 config 包读取这些变量，例如 01MVP 使用 @01mvp/config，OneSay 使用 @onesay/config。服务端变量只在 Worker / server runtime 使用；VITE_ 变量会进入浏览器端 bundle。

配置分为两类：

• 环境变量：通过 products/01mvp/packages/config/.env 和共享兜底 packages/config/.env 管理，控制外部服务连接和密钥
• 运行时配置：通过各功能包的配置代码管理，控制功能开关和业务逻辑

环境变量优先级：以 VITE_ 开头的变量暴露给浏览器端代码，其余仅在服务端可用。

Monorepo 里的维护方式

这套模板把共享 env schema 放在 packages/config，再用产品级 config 包承接产品默认值。核心原因是很多能力会跨越多个 package：products/01mvp/packages/api 需要数据库、支付和存储，products/01mvp/packages/auth 需要登录密钥，products/01mvp/apps/web 需要浏览器可见的公开地址。把变量散落到每个 app 目录，后面会很容易出现同一个变量多个名字、多个默认值、多个说明。

推荐维护方式如下：

以后 monorepo 增加新的产品时，先判断变量属于共享平台能力还是产品能力。共享变量定义放在 packages/config，产品默认值和产品级 .env.example 放在 products/<product>/packages/config。

本地脚本按下面顺序加载 env：产品 env 优先，shared env 作为兜底。这样 VITE_WEB_URL、VITE_SERVER_URL、EMAIL_FROM、AUTH_COOKIE_PREFIX 这类同名变量可以按产品覆盖。

products/<product>/packages/config/.env
packages/config/.env

01MVP 项目初始化时，优先复制对应产品的示例文件：

cp products/01mvp/packages/config/.env.example products/01mvp/packages/config/.env

如果一个变量只属于某个产品，优先把默认值放进该产品的 config 包，不要让其他产品代码直接读取它。

从旧项目迁移 env

从 Next.js 或旧项目迁过来时，不要直接复制整个 .env.local。先按新变量名映射，再确认哪些密钥会写生产资源。

R2、S3、支付、数据库、认证密钥都可能连接真实外部服务。迁移前先确认本地命令是否允许写入这些资源。

完整环境变量列表

PAGES_BASE_URL=https://pages.your-domain.com
DROP_R2_BUCKET_NAME=01mvp-drop-pages
DROP_R2_ACCOUNT_ID=<ACCOUNT_ID>
DROP_R2_ENDPOINT=https://<ACCOUNT_ID>.r2.cloudflarestorage.com
DROP_R2_ACCESS_KEY_ID=<ACCESS_KEY_ID>
DROP_R2_SECRET_ACCESS_KEY=<SECRET_ACCESS_KEY>
DROP_R2_REGION=auto

AI 默认值说明

聊天模型使用 OpenAI-compatible 接口。只要服务商兼容 Chat Completions 格式，就可以通过 OPENAI_BASE_URL 和 OPENAI_MODEL 切换。未配置时默认使用 DeepSeek：https://api.deepseek.com 和 deepseek-v4-flash。

Feature Flags

主要功能开关集中在环境变量 schema 和对应功能包中：

• 认证 -- AUTH_ENABLE_MAGIC_LINKS、AUTH_ENABLE_PHONE、AUTH_ENABLE_PASSKEYS、AUTH_ENABLE_TWO_FACTOR
• OpenAPI -- ENABLE_OPEN_API_DOCS
• 登录 CAPTCHA -- AUTH_CAPTCHA_ENABLED、AUTH_CAPTCHA_MODE
• AI 积分 -- CHAT_CREDITS_ENABLED、AI_MEDIA_CREDITS_ENABLED
• 支付渠道 -- PAYMENT_ENABLED_CHANNELS 配合 Stripe / ZPAY / Waffo 密钥

修改对应字段后重启开发服务器生效。

按功能查看

以下表格帮助你快速找到启用某个功能所需的变量。

安全提醒