@composy/env
v0.0.2
Published
Environment configuration management toolkit for LDesign.
Maintainers
Readme
@composy/env
面向 Node.js 项目的环境配置管理包,统一提供可编程 API 与 ldesign-env CLI,用于管理多环境 .env 文件、Schema 校验、敏感字段加密、搜索、导入导出、差异对比和备份恢复。
核心能力
- 多环境管理:约定使用
.env.development、.env.test、.env.staging、.env.production等文件。 - Schema 校验:支持
string、number、boolean、json、array,并带有必填、枚举、范围、长度、正则和默认值。 .env友好类型容错:数字字符串、布尔字符串、JSON 字符串和逗号分隔数组都可以按 Schema 自动校验。- 敏感字段保护:基于
AES-256-GCM提供字符串加密、字段级加密和自动解密。 - 工具化能力:支持配置搜索、模板初始化、格式转换、diff、备份、恢复和完整性校验。
- 单包交付:
@composy/env同时承载源码 API、类型定义和 CLI,无需再拆core/cli子包。
安装
作为项目依赖
pnpm add -D @composy/env全局安装 CLI
pnpm add -g @composy/env
# 或
npm install -g @composy/env文件约定
默认在项目根目录使用以下文件:
.env.schema.json # Schema 定义
.env.development # development 环境配置
.env.production # production 环境配置
.env.current # 当前激活环境
.env.example # 示例配置
.env.key # 加密密钥,不应提交到版本控制
.env-backups/ # 备份目录快速开始
1. 初始化项目
ldesign-env init或者直接使用内置模板:
ldesign-env template use nextjs
ldesign-env template use nestjs --envs development,staging,production2. 切换和验证环境
ldesign-env list
ldesign-env use development
ldesign-env validate --all3. 查询和修改配置
ldesign-env get API_URL
ldesign-env set API_URL https://api.example.com
ldesign-env set DB_PORT 5432 --type number
ldesign-env delete DEBUG4. 搜索、导出、备份
ldesign-env search API_URL
ldesign-env export production --format yaml
ldesign-env backup create --name release-2026-04-25
ldesign-env backup listSchema 示例
{
"API_URL": {
"type": "string",
"required": true,
"pattern": "^https?://",
"description": "API 服务地址"
},
"DB_PORT": {
"type": "number",
"default": 5432,
"min": 1,
"max": 65535,
"description": "数据库端口"
},
"DEBUG": {
"type": "boolean",
"default": false,
"description": "调试模式"
},
"DB_PASSWORD": {
"type": "string",
"required": true,
"secret": true,
"minLength": 8,
"description": "数据库密码"
}
}说明:
number字段允许.env中写成"5432",验证时会自动转换。boolean字段允许"true"、"false"、"1"、"0"。json字段允许直接写 JSON 字符串。array字段允许 JSON 数组字符串或逗号分隔字符串。
CLI 命令
基础命令
ldesign-env init
ldesign-env list
ldesign-env use <environment>
ldesign-env validate [environment] --all
ldesign-env get <key>
ldesign-env set <key> <value>
ldesign-env delete <key>
ldesign-env diff <from> <to>
ldesign-env search <query>模板命令
ldesign-env template list
ldesign-env template use <template>
ldesign-env template init内置模板:
nextjsnestjsexpressreactvuedocker
加密命令
ldesign-env encrypt "plain-text"
echo "plain-text" | ldesign-env encrypt --stdin
ldesign-env decrypt "encrypted:..."
ldesign-env decrypt "encrypted:..." --show导入导出命令
ldesign-env import ./config.json --env production
ldesign-env export production --format env
ldesign-env export production --format json
ldesign-env export production --format yaml
ldesign-env export production --format toml
ldesign-env export production --format shell
ldesign-env export production --mask-secrets备份命令
ldesign-env backup create
ldesign-env backup list
ldesign-env backup restore <backupId>
ldesign-env backup verify <backupId>
ldesign-env backup delete <backupId>
ldesign-env backup cleanup --keep 5API 使用
环境加载与校验
import { EnvManager } from '@composy/env'
const manager = new EnvManager({
baseDir: process.cwd(),
enableCache: true,
cacheTTL: 60_000,
encryptionKey: process.env.LDESIGN_ENV_KEY,
watchFiles: true,
})
await manager.load('production')
const apiUrl = manager.get<string>('API_URL')
const dbPort = manager.get<number>('DB_PORT', 5432)
const validation = manager.validate()
if (!validation.valid) {
throw new Error(JSON.stringify(validation.errors, null, 2))
}配置修改与持久化
manager.set('LOG_LEVEL', 'info')
manager.set('DEBUG', false)
await manager.save()生命周期与文件监听
watchFiles: true 会监听当前项目目录下的 .env.* 文件和当前环境标记,外部修改会以防抖方式重新加载;读取或校验失败时保留最后一次成功的内存状态并输出错误。构造阶段的自动加载默认失败即抛错,只有显式设置 ignoreAutoLoadErrors: true 才会降级为告警。
长期运行进程应在不再使用时调用 manager.destroy(),以关闭文件监听、取消待处理重载并释放缓存清理定时器。销毁后的管理器不再接受配置读写、加密或监听操作。
密钥轮换
rotateKey() 会扫描项目中的全部 .env.<environment> 文件,将 Schema 标记为 secret 的明文/旧密文,以及其他带 encrypted: 前缀的字段,迁移到新密钥后再更新 .env.key:
await manager.rotateKey(process.env.NEW_LDESIGN_ENV_KEY as string)轮换会先完成全部解析和新内容准备,再按环境文件到 .env.key 的顺序原子写入;写入失败会逆序恢复已写入文件,只有全部成功后才切换管理器内存密钥。saveKey() 只保存并切换密钥,不会迁移已有密文;需要更换项目密钥时应使用 rotateKey()。
环境对比
const diff = await manager.diff('staging', 'production')
console.log(diff.modified)自定义校验
import type { CustomValidationRule } from '@composy/env'
const portRule: CustomValidationRule = {
name: 'port-allowlist',
validate(value, fieldName) {
if (fieldName === 'PORT' && value !== 3000 && value !== 8080) {
return {
field: fieldName,
message: 'PORT 仅允许使用 3000 或 8080',
value,
}
}
return null
},
}公开模块
EnvManager:核心环境管理门面。ConfigLoader:.env/ Schema 文件读取与序列化。SchemaValidator:Schema 校验和类型容错。CryptoManager:字符串与字段级加密。ConfigMerger:合并、diff、扁平化和反扁平化。ImportExportManager:env/json/yaml/toml转换。SearchManager:多模式配置搜索与高亮。BackupManager:备份创建、恢复、校验和清理。
目录结构
tools/env/
├── .ldesign/
│ ├── pack.config.ts
│ ├── eslint.config.js
│ └── tsconfig.json
├── eslint.config.js # ESLint 兼容入口
├── tsconfig.json # TypeScript 兼容入口
├── bin/
│ └── ldesign-env.js
├── docs/
├── src/
│ ├── backup/
│ ├── cli/
│ │ ├── commands/
│ │ └── shared/
│ ├── config/
│ │ ├── cache/
│ │ ├── exchange/
│ │ ├── files/
│ │ ├── schema/
│ │ ├── search/
│ │ ├── templates/
│ │ └── utilities/
│ ├── environment/
│ ├── security/
│ └── shared/
│ ├── errors/
│ └── types/
├── tests/
└── package.json构建与开发
构建使用 @composy/pack(工作区工具包 tools/tsup-config);权威配置位于 .ldesign/pack.config.ts,并对 src/**/*.ts 中的所有源码文件生成:
ESLint 与 TypeScript 主配置分别位于 .ldesign/eslint.config.js 和 .ldesign/tsconfig.json;根目录配置文件保留为兼容入口。
ESM产物CJS产物.d.ts类型声明
常用命令:
pnpm run type-check
pnpm run lint:check
pnpm test
pnpm run build
pnpm run verify设计约束
EnvManager是对外主门面,CLI 不应绕过它直接拼装核心逻辑。.env文件序列化必须对引号、空格、注释符、对象和数组保持稳定输出。- 加密值统一使用
encrypted:前缀;新密文使用带随机 salt 的encrypted:v2:envelope,同时兼容读取历史encrypted:密文。 - 备份文件自带校验和,恢复前必须验证完整性。
- 敏感字段搜索默认关闭,除非显式传入
--include-secrets。
通过 @composy/cli 统一接入
通过 @composy/cli 统一接入
- 接入类型:
bin - 统一命令:
ldesign env - 命令别名:
lenv - 包内原生 bin:
ldesign-env、lenv
当前包通过独立 bin 接入,统一命令会转发到包自身 CLI。
pnpm add -D @composy/cli
ldesign env --help
ldesign tools run env --helpEnv Doctor 诊断
ldesign-env doctor 用于在本地开发、CI 或发布前检查环境配置健康状态。它会汇总:
.env.schema.json是否存在且可解析.env.current是否指向真实存在的环境- 每个
.env.<environment>是否缺少必填字段 - 是否存在 schema 未声明字段
- schema 校验错误
secret: true字段是否仍为明文
常用命令:
ldesign-env doctor
ldesign-env doctor --summary
ldesign-env doctor --json
ldesign-env doctor --env development,production
ldesign-env doctor --allow-unknown-keys编程入口:
import { EnvDoctor } from '@composy/env'
const report = new EnvDoctor({ baseDir: process.cwd() }).inspect()
if (report.status === 'error') {
process.exit(1)
}