配置体系

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

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

cp products/muse/packages/config/.env.example products/muse/packages/config/.env

根目录 packages/config/.env 是共享配置层，适合放多个产品共用的默认值，例如 AI 模型、短信、统计或平台级服务商配置。需要这些共享值时，再复制它：

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

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

postgresql://localhost:5432/muse_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 包读取这些变量，例如 Muse 使用 @muse/config，未来新产品可以使用自己的 @<product>/config。服务端变量只在 Worker / server runtime 使用；VITE_ 变量会进入浏览器端 bundle。

配置分为两类：

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

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

Monorepo 里的维护方式

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

推荐维护方式如下：

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

本地脚本按下面顺序加载 env：产品 env 优先，shared env 随后补齐共享配置。这样 VITE_WEB_URL、VITE_SERVER_URL、EMAIL_FROM、AUTH_COOKIE_PREFIX、DATABASE_URL 这类产品差异项可以按产品覆盖；OPENAI_BASE_URL、OPENAI_MODEL、短信服务商、统计 ID 这类跨产品默认值可以统一放在根配置。

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

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

cp products/muse/packages/config/.env.example products/muse/packages/config/.env

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

如果多个产品使用同一个 AI 服务商和默认模型，推荐把它们放在 packages/config/.env：

OPENAI_API_KEY="your-api-key"
OPENAI_BASE_URL="https://api.deepseek.com"
OPENAI_MODEL="deepseek-v4-flash"

产品级 env 只在 Muse 需要单独切换模型、单独计费或连接独立 provider 时再覆盖这些值。

从旧项目迁移 env

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

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

完整环境变量列表

AI 默认值说明

聊天模型使用 OpenAI-compatible 接口。只要服务商兼容 Chat Completions 格式，就可以通过 OPENAI_BASE_URL 和 OPENAI_MODEL 切换。本地开发可以保留 MUSE_AI_MOCK_OUTPUT=true 先跑通 UI 和订单流程。

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、CHAT_CREDIT_COST
• Muse 模块 -- MUSE_MODULE_PUBLIC_HOME、MUSE_MODULE_PUBLIC_PROFILES、MUSE_MODULE_WECHAT_AUTH、MUSE_MODULE_CREDITS_PACKS、MUSE_MODULE_AI_TOOLS
• 支付渠道 -- PAYMENT_ENABLED_CHANNELS 配合 ZPay 或扩展 Provider 密钥

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

按功能查看

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

安全提醒