npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@composy/env

v0.0.2

Published

Environment configuration management toolkit for LDesign.

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,production

2. 切换和验证环境

ldesign-env list
ldesign-env use development
ldesign-env validate --all

3. 查询和修改配置

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 DEBUG

4. 搜索、导出、备份

ldesign-env search API_URL
ldesign-env export production --format yaml
ldesign-env backup create --name release-2026-04-25
ldesign-env backup list

Schema 示例

{
  "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

内置模板:

  • nextjs
  • nestjs
  • express
  • react
  • vue
  • docker

加密命令

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 5

API 使用

环境加载与校验

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 --help

Env 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)
}