@efebia/ one- env
为有运行时间验证和CLI工具的Node.js应用程序进行类型安全的环境配置管理.
特征
- 🔒 类型安全 有完整类型脚本支持的环境变量
- ✅ 运行时间验证 使用 Zod 计划
- 🛠️ CLI 工具 用于生成、验证和管理环境文件
- 🌍 多个来源: 从 YAML 文件或 JSON 环境变量装入
- 🚀 生产就绪: 验证 AWS 保密管理器配置
- 📤 推拉( P): 与 AWS 保密管理器同步机密
- 💡 方便开发者: 所有环境变量自动完成
安装
# 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. 界定环境计划
// 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. 申请中的用途
// 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. 备选案文:立即初始化
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 工具:
生成环境文件
创建一个带有默认值的新环境文件 :
# 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
校验环境文件
检查您的环境文件是否有效 :
# 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 保密管理器中的环境变量 :
# 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 保密管理器拖入本地文件 :
# 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 密件管理器 :
# 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
典型的工作流程
更新开发中的单一值:
# 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)
创建并立即初始化环境加载器 .
const env = createEnv({
schema: ZodSchema,
file: './env.yml' // or
env: 'CONFIG_JSON' // for JSON from environment variable
});
createEnvWithInit(schema)
创建环境加载器,并推迟初始化.
const env = createEnvWithInit(schema);
// Initialize later
env.init({ file: './env.yml' });
// or
env.init({ env: 'CONFIG_JSON' });
方法
get(key) 编号 : get(...keys)
获得具有类型安全性的一个或多个环境值 :
// Single value
const port = env.get('port'); // number
// Multiple values
const { port, nodeEnv } = env.get('port', 'nodeEnv');
getOptional(key) 编号 : getOptional(...keys)
获取可选环境值 :
const timeout = env.getOptional('cacheTimeout'); // number | undefined
getAll()
获取所有已验证的环境变量 :
const config = env.getAll(); // Fully typed object
最佳做法
1. 司马组织
将您的计划保存在单独的文件中, 以便重复使用 :
// 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. 单子图案
创建单子实例以避免初始化问题:
// 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 对等依赖)
许可证
麻省理工学院
捐款
欢迎捐款! 请随意提交拉力请求.
支助
对于错误和特性请求,请 创建问题。 。 。 .
更改日志
1.02 (即将进行)
- 添加
pull从 AWS 保密管理器下载机密的命令 - 重命名
upload命令改为push工作流程一致 - Fix Node.js 版本要求 (>= 20.0.0)