For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh/docs/modules/config.md (or send Accept: text/markdown).

环境与配置

整个工作区唯一的已验证模式。

询问本指南

进行一项配置更改并检查它

从正在运行的 Web 应用程序开始。在编辑器中打开apps/web/.env.local；如果不存在，请使用 Web 教程将 .env.example 复制到那里。对于无害的首次检查，请找到 EMAIL_PROVIDER=local 并将其保留在本地。此设置将产品电子邮件发送到本地预览而不是真正的收件箱。不要将 KEY=value 线粘贴到终端中。

对于您启用的每项服务，请遵循该提供商的设置指南，仅替换指定值，保存文件，使用 Ctrl + C 停止 Web 服务器，然后使用以下命令重新启动。如果验证指定了丢失的密钥，请重新打开此文件并将该密钥与提供程序指南进行比较。仅对数据库迁移使用的值保持 root .env 同步；单独复制它不会配置 Next.js。

corepack pnpm --filter @supastack/web dev

从环境示例开始

根目录的 .env.example 是配置清单。共享校验在 packages/config。把选定的应用环境与供应商模式放在一起审阅；本地界面并不等于生产凭证策略。

无凭证的参考模式要求 local/test 应用配置与 fake/本地供应商。选择生产供应商会改变运行要求。

让密钥留在 API 之后

认证密钥、数据库凭证、供应商密钥、Stripe 密钥与 Trigger 凭证都属于服务端。绝不要给它们加 NEXT_PUBLIC_ 或 EXPO_PUBLIC_ 前缀。安装过程中不要打印它们，也不要把它们放进错误响应。

浏览器只拿到公开配置与允许的模型别名。工作区归属、权限决策、预算与供应商选择都由服务端强制执行。

先用再信：检查变更

通过现有的 config 包校验配置，并运行相关的确定性测试。准备好验证真实集成时，再走单独 opt-in 的供应商冒烟路径。

corepack pnpm test
corepack pnpm check
corepack pnpm build

安装与配置

packages/config 是唯一解析 process.env 的地方:zod 模式产出类型化的 ServerConfig 和 PublicConfig,提供商选择以 kinds 表达 —— providers.ai、providers.billing、providers.email、providers.jobs、providers.storage 各自解析为一个命名的适配器及其必填字段。

启用提供商会使其凭据成为必填:开启社交登录、s3 存储 kind 或 resend 邮件 kind 会让启动失败并指出缺失的变量,而不是之后在运行时出现意外。

STORAGE_PROVIDER=s3
STORAGE_BUCKET=kit
STORAGE_ENDPOINT=https://s3.example
STORAGE_PUBLIC_BASE_URL=https://cdn.example
# → config rejects the env if a required field is missing

实现流程

在服务器边界通过 parseServerConfig 读取配置,并将类型化的值向内传递 —— 不要在功能代码中触碰 process.env。公共配置是一个单独的、刻意保持小巧的对象,可以安全地序列化给客户端。

产品专属的 env 属于消费产品自己的模式。不要为单个产品的需求而膨胀套件模式。

验证与排障

更改模式后运行 config 包测试,并确认缺失的必填变量会在错误中指明自身。本地能解析但生产中不能解析的 env 通常意味着一个未文档化的必填字段。