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），然后定义环境映射、环境文件目标和 gitignore 行为。

了解更多：

• 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