better-env

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Work With better-env In A Repo

在代码仓库中使用better-env

Type-safe environment config modules

类型安全的环境配置模块

Follow this best practice to manage environment variables in TypeScript applications with full type safety and clear server/public boundaries.

better-env

exports

configSchema

to define typed env modules and recommends placing them in feature-level

config.ts

files (for example

src/lib/auth/config.ts

and

src/lib/database/config.ts

Learn more:

```
references/config-schema.md
```

遵循此最佳实践，在TypeScript应用中管理环境变量，同时具备完整的类型安全性和清晰的服务端/客户端边界。

better-env

导出

configSchema

用于定义类型化环境模块，并建议将其放置在功能级别的

config.ts

文件中（例如

src/lib/auth/config.ts

和

src/lib/database/config.ts

）。

了解更多：

```
references/config-schema.md
```

Validate existence of all env variables in the current environment

验证当前环境中所有环境变量的存在性

Run env validation early so missing or invalid values fail fast before

dev

build

, or deploy steps.

better-env validate --environment <name>

loads

.env*

files with Next.js semantics, discovers

src/lib/*/config.ts

modules, and checks every declared variable from your

configSchema

modules.

If your dotenv files intentionally include keys that are not referenced by config modules, add per-env suppressions in

better-env.ts

environments.<env>.ignoreUnused: string[]

These suppress only the selected local environment during

validate

. Adapter defaults are merged in automatically; for Vercel,

VERCEL_OIDC_TOKEN

is ignored by default in

development

preview

, and

production

Learn more:

```
references/env-validation.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
```

Configure runtime syncing between local files and hosted providers

配置本地文件与托管平台之间的运行时同步

Use runtime configuration to keep local dotenv targets aligned with provider environments while preserving safe defaults.

Create

better-env.ts

with

defineBetterEnv(...)

and an adapter (

vercelAdapter

netlifyAdapter

railwayAdapter

, or

cloudflareAdapter

), then define environment mappings, env-file targets, and gitignore behavior.

Learn more:

```
references/config.md
```
```
references/runtime.md
```

使用运行时配置保持本地dotenv目标与平台环境一致，同时保留安全的默认值。

通过

defineBetterEnv(...)

创建

better-env.ts

并配置适配器（

vercelAdapter

、

netlifyAdapter

、

railwayAdapter

或

cloudflareAdapter

），然后定义环境映射、env文件目标以及gitignore规则。

了解更多：

```
references/config.md
```
```
references/runtime.md
```

Use the CLI for day-to-day environment operations

使用CLI进行日常环境操作

The CLI gives a consistent workflow for initialization, sync, validation, and remote variable management, which is great for local development and CI automation.

Choose the command runner to match the repo:

Use
```
npx
```
in npm/pnpm-based repos (for example lockfiles like
```
package-lock.json
```
or
```
pnpm-lock.yaml
```
and scripts run via
```
npm
```
/
```
pnpm
```
).
Use
```
bunx
```
in Bun-based repos (for example
```
bun.lock
```
and scripts run via
```
bun
```
).
Keep commands aligned with the project's existing package manager/runtime conventions; do not mix runners unless the repo already does.

Recommended flow in a repo:

Run
```
better-env init
```
once to verify adapter prerequisites.
Run
```
better-env pull --environment <name>
```
to sync local env files.

Run

better-env validate --environment <name>

before app startup/build.

Use
```
add
```
,
```
upsert
```
,
```
update
```
,
```
delete
```
, and
```
load
```
for remote env changes.

Choose command behavior intentionally:

```
upsert
```
for idempotent automation and scripts
```
add
```
when duplicate keys should fail
```
update
```
when missing keys should fail
```
delete
```
to remove remote keys
```
load
```
for batch updates from dotenv files

Learn more:

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

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

根据代码仓库选择对应的命令运行器：

在基于npm/pnpm的仓库中使用
```
npx
```
（例如包含
```
package-lock.json
```
或
```
pnpm-lock.yaml
```
锁文件，且脚本通过
```
npm
```
/
```
pnpm
```
运行）。
在基于Bun的仓库中使用
```
bunx
```
（例如包含
```
bun.lock
```
锁文件，且脚本通过
```
bun
```
运行）。
保持命令与项目现有的包管理器/运行时约定一致；除非仓库本身已经混用，否则不要混合使用不同的运行器。

推荐的仓库使用流程：

运行一次
```
better-env init
```
以验证适配器的前置条件。
运行
```
better-env pull --environment <name>
```
同步本地环境文件。

在应用启动/构建前运行

better-env validate --environment <name>

。

使用
```
add
```
、
```
upsert
```
、
```
update
```
、
```
delete
```
和
```
load
```
命令管理远程环境变量。

根据需求选择合适的命令：

```
upsert
```
：适用于幂等自动化和脚本场景
```
add
```
：当重复键值应触发报错时使用
```
update
```
：当缺失键值应触发报错时使用
```
delete
```
：删除远程键值
```
load
```
：从dotenv文件批量更新

了解更多：

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