better-env

在代码仓库中使用 better-env

类型安全的环境配置模块

遵循此最佳实践，在 TypeScript 应用中管理环境变量，实现完整的类型安全和清晰的服务端／公开端边界。

better-env 导出 configSchema，用于定义类型化的环境变量模块，并建议将这些模块放在功能级别的 config.ts 文件中（例如 src/lib/auth/config.ts 和 src/lib/database/config.ts）。

了解详情：

• references/config-schema.md

验证当前环境中所有环境变量是否存在

尽早运行环境变量验证，以便在 dev、build 或部署步骤之前快速发现缺失或无效的值。

better-env validate --environment <name> 会按照 Next.js 语义加载 .env* 文件，查找 src/lib/*/config.ts 模块，并检查 configSchema 模块中声明的所有变量。

如果你的 dotenv 文件有意包含配置模块未引用的键，请在 better-env.ts 中添加针对各环境的忽略项：

environments.<env>.ignoreUnused: string[]

这些忽略项只会在 validate 时对选定的本地环境生效。 适配器默认忽略项会自动合并；对于 Vercel，VERCEL_OIDC_TOKEN 默认会在 development、preview 和 production 中被忽略。

了解详情：

• references/env-validation.md

配置本地文件与托管服务提供商之间的运行时同步

使用运行时配置，让本地 dotenv 目标与服务提供商环境保持一致，同时保留安全的默认设置。

创建 better-env.ts，使用 defineBetterEnv(...) 和一个适配器（vercelAdapter、netlifyAdapter、railwayAdapter、cloudflareAdapter、flyAdapter 或 convexAdapter）。

对于标准的 Vercel 设置，建议使用最精简的配置：

export default defineBetterEnv({ adapter: vercelAdapter() });

如果 environments 配置块只是重复适配器默认值，请勿添加。 仅在确实需要自定义映射、自定义环境文件或针对各环境的 ignoreUnused 行为时，才添加 environments。

了解详情：

• references/config.md
• references/runtime.md

使用 CLI 执行日常环境操作

CLI 为初始化、同步、验证和远程变量管理提供一致的工作流，非常适合本地开发和 CI 自动化。

选择与代码仓库相匹配的命令运行器：

• 在基于 npm/pnpm 的代码仓库中使用 npx（例如使用 package-lock.json 或 pnpm-lock.yaml 等锁文件，且通过 npm/pnpm 运行脚本）。
• 在基于 Bun 的代码仓库中使用 bunx（例如使用 bun.lock，且通过 bun 运行脚本）。
• 命令应遵循项目现有的包管理器／运行时约定；除非代码仓库已有此做法，否则不要混用运行器。

在代码仓库中建议按以下流程操作：

1. 运行一次 better-env init，验证适配器的先决条件。
2. 运行 better-env pull --environment <name>，同步本地环境文件。
3. 在应用启动／构建之前运行 better-env validate --environment <name>。
4. 使用 add、upsert、update、delete 和 load 管理远程环境变量。

有意选择命令行为：

• 使用 upsert 进行幂等自动化和脚本操作
• 当重复键应报错时使用 add
• 当键缺失应报错时使用 update
• 使用 delete 移除远程键
• 使用 load 从 dotenv 文件批量更新

了解详情：

• references/cli.md
• references/vercel-adapter.md