# @efebia/one-env 中文文档

规范地址：https://npmcn.com/package/%40efebia/one-env/

版本：1\.0\.4
npm 元数据更新时间：2026-11-12T13:24:17.049Z
中文译文更新时间：2026-11-13T08:05:26.318Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40efebia/one-env
原文对照：https://npmcn.com/package/%40efebia/one-env/?lang=original
项目主页：https://github.com/efebia-com/be-libs#readme
源码仓库：https://github.com/efebia-com/be-libs

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：120 kB，60 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：4 个
- peer 依赖：zod ^4\.0\.5
- 首次发布：2025-07-20T18:58:48.625Z
- 最新版本发布：2026-11-12T13:24:16.526Z
- 近 30 天下载量：3460（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 2 个）

## 中文简介

具有验证和CLI工具的型式安全环境配置

## 安装

```sh
npm install @efebia/one-env
```

也可以使用：`pnpm add @efebia/one-env`、`yarn add @efebia/one-env`、`bun add @efebia/one-env`

## README

# @efebia/ one- env

为有运行时间验证和CLI工具的Node.js应用程序进行类型安全的环境配置管理.

## 特征

-   🔒 **类型安全** 有完整类型脚本支持的环境变量
-   ✅ **运行时间验证** 使用 Zod 计划
-   🛠️ **CLI 工具** 用于生成、验证和管理环境文件
-   🌍 **多个来源**: 从 YAML 文件或 JSON 环境变量装入
-   🚀 **生产就绪**: 验证 AWS 保密管理器配置
-   📤 **推拉( P)**: 与 AWS 保密管理器同步机密
-   💡 **方便开发者**: 所有环境变量自动完成

## 安装

```bash
# Using npm
npm install @efebia/one-env zod

# Using yarn
yarn add @efebia/one-env zod

# Using pnpm
pnpm add @efebia/one-env zod
```

注:Zod (^4. 0.0) 是同级依赖,必须单独安装.

## 快速启动

### 1\. 界定环境计划

```typescript
// env-schema.ts
import { z } from 'zod/v4';

const EnvSchema = z.object({
  // Application
  port: z.coerce.number().positive().default(3000),
  nodeEnv: z.enum(['development', 'production', 'test']).default('development'),
  
  // Database
  databaseUrl: z.string().url().describe('PostgreSQL connection URL'),
  
  // API Keys
  apiKey: z.string().min(32).describe('External API key'),
  
  // Feature flags
  enableCache: z.boolean().default(true),
  cacheTimeout: z.coerce.number().positive().optional().default(3600),
});

export default EnvSchema;
```

### 2\. 申请中的用途

```typescript
// env.ts
import { createEnvWithInit } from '@efebia/one-env';
import EnvSchema from './env-schema.js';

// Create env instance (singleton pattern)
const env = createEnvWithInit(EnvSchema);
export default env;

// app.ts
import env from './env.js';

// Initialize with YAML file
env.init({ file: './env.local.yml' });

// Or initialize with JSON from environment variable
env.init({ env: 'APP_CONFIG' });

// Use with full type safety
export const config = {
  port: env.get('port'),
  database: env.get('databaseUrl'),
  cache: {
    enabled: env.get('enableCache'),
    timeout: env.get('cacheTimeout'),
  }
};
```

**说明**: 使用 `createEnvWithInit` 作为单子帮助计算货币,防止错误调用 `env.get()` 由于进口订单问题,在初始化之前.

### 3\. 备选案文:立即初始化

```typescript
import { createEnv } from '@efebia/one-env';
import EnvSchema from './env-schema.js';

// Initialize immediately
const env = createEnv({ 
  schema: EnvSchema, 
  file: './env.local.yml' 
});

// Use directly
const port = env.get('port');
```

## CLI 工具

@efebia/ one- env 包含管理您环境配置的强大的 CLI 工具:

### 生成环境文件

创建一个带有默认值的新环境文件 :

```bash
# Generate env.local.yml with defaults
one-env generate -s ./env-schema.js

# Generate with custom output
one-env generate -s ./env-schema.js -o env.prod.yml

# Force overwrite existing file
one-env generate -s ./env-schema.js --force
```

### 校验环境文件

检查您的环境文件是否有效 :

```bash
# Validate env.local.yml
one-env validate -s ./env-schema.js

# Validate specific file
one-env validate -s ./env-schema.js --file env.prod.yml

# Output as JSON (for CI/CD)
one-env validate -s ./env-schema.js --json
```

### 验证 AWS 密钥

验证存储在 AWS 保密管理器中的环境变量 :

```bash
# Validate AWS secrets
one-env validate-aws -s ./env-schema.js --secret-name my-app/prod

# With specific AWS profile
one-env validate-aws -s ./env-schema.js --secret-name my-app/prod --profile production

# With specific region
one-env validate-aws -s ./env-schema.js --secret-name my-app/prod --region us-east-1
```

### 从 AWS 保密管理器中提取

将您的环境配置从 AWS 保密管理器拖入本地文件 :

```bash
# Pull from AWS to local file
one-env pull -s ./env-schema.js --secret-name dev-envs

# Pull with custom output file
one-env pull -s ./env-schema.js --secret-name prod-envs --output env.prod.yml

# Force overwrite existing file
one-env pull -s ./env-schema.js --secret-name dev-envs --force

# With specific AWS profile and region
one-env pull -s ./env-schema.js --secret-name dev-envs --profile development --region us-east-1
```

### 推向 AWS 保密管理器

将本地环境配置推进到 AWS 密件管理器 :

```bash
# Push to AWS (with confirmation prompt)
one-env push -s ./env-schema.js --file env.prod.yml --secret-name prod-envs

# Push with environment tag
one-env push -s ./env-schema.js --file env.prod.yml --secret-name prod-envs --environment production

# Dry-run to preview what will be pushed
one-env push -s ./env-schema.js --file env.prod.yml --secret-name prod-envs --dry-run

# Skip confirmation prompt (for CI/CD)
one-env push -s ./env-schema.js --file env.prod.yml --secret-name prod-envs --force

# With specific AWS profile and region
one-env push -s ./env-schema.js --file env.prod.yml --secret-name prod-envs --profile production --region us-east-1
```

### 典型的工作流程

更新开发中的单一值:

```bash
# 1. Pull current configuration
one-env pull -s ./env-schema.js --secret-name dev-envs

# 2. Edit the file locally
vim env.pulled.yml  # Change databaseUrl or any other value

# 3. Push changes back
one-env push -s ./env-schema.js --file env.pulled.yml --secret-name dev-envs
```

**安全说明**:从不执行包含实际机密的文件. 使用 `.gitignore` 排除带有敏感数据的环境文件.

## API 参考

### `createEnv(options)`

创建并立即初始化环境加载器 .

```typescript
const env = createEnv({
  schema: ZodSchema,
  file: './env.yml'    // or
  env: 'CONFIG_JSON'   // for JSON from environment variable
});
```

### `createEnvWithInit(schema)`

创建环境加载器,并推迟初始化.

```typescript
const env = createEnvWithInit(schema);

// Initialize later
env.init({ file: './env.yml' });
// or
env.init({ env: 'CONFIG_JSON' });
```

### 方法

#### `get(key)` 编号 : `get(...keys)`

获得具有类型安全性的一个或多个环境值 :

```typescript
// Single value
const port = env.get('port'); // number

// Multiple values
const { port, nodeEnv } = env.get('port', 'nodeEnv');
```

#### `getOptional(key)` 编号 : `getOptional(...keys)`

获取可选环境值 :

```typescript
const timeout = env.getOptional('cacheTimeout'); // number | undefined
```

#### `getAll()`

获取所有已验证的环境变量 :

```typescript
const config = env.getAll(); // Fully typed object
```

## 最佳做法

### 1\. 司马组织

将您的计划保存在单独的文件中, 以便重复使用 :

```typescript
// env-schema.ts
export default z.object({
  // Group related variables
  // Database
  dbHost: z.string(),
  dbPort: z.coerce.number(),
  dbName: z.string(),
  
  // Add descriptions for documentation
  apiKey: z.string().describe('API key for external service'),
  
  // Use defaults for development
  logLevel: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
});
```

### 2\. 环境档案

默认的 schema 自动生成环境文件 :

```
env.local.yml      # Local development (gitignored)
```

使用 `generate` 命令从您的计划创建新的环境文件,从而消除例如文件的需要.

### 3\. 单子图案

创建单子实例以避免初始化问题:

```typescript
// env.ts
import { createEnvWithInit } from '@efebia/one-env';
import EnvSchema from '../../env-schema.js';

const env = createEnvWithInit(EnvSchema);
export default env;
```

此模式 :

-   在初始化期间防止种族条件
-   优雅地处理导入顺序
-   保证应用程序的状态一致
-   避免调用错误 `env.get()` 在此之前 `env.init()`

## 处理错误

@efebia/ one- env 为配置问题提供清晰的错误消息 :

```
Environment validation failed:
  - port: Expected number, received string
  - databaseUrl: Invalid URL
  - apiKey: String must contain at least 32 characters
```

## 所需资源

-   节点.js >= 20.0.0
-   Zod (^ 4. 0.0 对等依赖)

## 许可证

麻省理工学院

## 捐款

欢迎捐款! 请随意提交拉力请求.

## 支助

对于错误和特性请求,请 [创建问题](https://github.com/efebia/be-libs/issues)。 。 。 .

## 更改日志

### 1.02 (即将进行)

-   添加 `pull` 从 AWS 保密管理器下载机密的命令
-   重命名 `upload` 命令改为 `push` 工作流程一致
-   Fix Node.js 版本要求 (>= 20.0.0)

## 常见问题

### @efebia/one-env 是什么？

具有验证和CLI工具的型式安全环境配置

### 如何安装 @efebia/one-env？

在项目目录运行 npm install @efebia/one-env，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.0\.5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 one-env，可以用 npx one-env 直接运行。

### @efebia/one-env 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @efebia/one-env 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @efebia/one-env 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @efebia/one-env 可以商用吗？

@efebia/one-env 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @efebia/one-env 的下载量有多少？

根据 npm 官方下载统计，@efebia/one-env 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,460 次，日均约 115 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @efebia/one-env 还在维护吗？

最新版本 1\.0\.4 发布于 2026/11/12（1 天前）；至今共发布 5 个版本，其中过去 12 个月发布了 2 个；首次发布于 2025/07/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。