# @envilder/sdk 中文文档

规范地址：https://npmcn.com/package/%40envilder/sdk/

版本：1\.2\.0
npm 元数据更新时间：2026-11-08T20:35:14.862Z
中文译文更新时间：2026-11-13T21:33:55.737Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40envilder/sdk
原文对照：https://npmcn.com/package/%40envilder/sdk/?lang=original
项目主页：https://envilder.com/docs/sdks/nodejs/
源码仓库：https://github.com/macalbert/envilder

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

- 包体积（解压后）：126 kB，90 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：4 个
- 首次发布：2026-04-30T13:14:20.337Z
- 最新版本发布：2026-11-08T20:35:14.567Z
- 近 30 天下载量：3049（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

从 AWS SSM 参数存储器或 Azure 密钥断层直接装入您的节点.js 进程——不需要.env 文件.

## 安装

```sh
npm install @envilder/sdk
```

也可以使用：`pnpm add @envilder/sdk`、`yarn add @envilder/sdk`、`bun add @envilder/sdk`

## README

# (原始内容存档于2018-09-21). Envilder Node.js SDK

[![Coverage Report](https://img.shields.io/badge/coverage-report-green.svg)](https://macalbert.github.io/envilder/nodejs/) [![npm version](https://img.shields.io/npm/v/%40envilder/sdk.svg)](https://www.npmjs.com/package/@envilder/sdk) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/macalbert/envilder/blob/main/LICENSE)

安全装入环境变量 **AWS SSM 参数存储** 或者说 **Azure 密钥断层** 直接输入您的Node.js应用程序. 零卖家锁定:保密留入你云.

部分 [诽谤者](https://github.com/macalbert/envilder) 项目.

## 先决条件

-   节点.js 22.12+
-   **AWS 提供者**: 配置 AWS 证书( CLI, 环境变量, 或 IAM 角色)
-   **Azure 提供者**: 通过 `az login`,管理身份,或环境变量

## 安装

```bash
npm install @envilder/sdk
```

## 快速启动

### 单线: 解析+注入

```typescript
import { Envilder } from '@envilder/sdk';

// Resolve secrets and inject into process.env
await Envilder.load('envilder.json');

console.log('DB_PASSWORD loaded:', !!process.env.DB_PASSWORD);
```

### 解决不注射

```typescript
import { Envilder } from '@envilder/sdk';

const secrets = await Envilder.resolveFile('envilder.json');
console.log(secrets.get('DB_PASSWORD')); // avoid logging secrets in production
```

### Azure 密钥断层

在地图文件中设置提供者 `$config`; 值是密钥默认密名 :

```json
{
  "$schema": "https://envilder.com/schema/map-file.v1.json",
  "$config": {
    "provider": "azure",
    "vaultUrl": "https://my-vault.vault.azure.net"
  },
  "DB_PASSWORD": "myapp-prod-db-password"
}
```

数值按所写发送到密钥默认值, 但斜线变为连字符: 路径样式值 例如 `/myapp/prod/db-password` 改为 `myapp-prod-db-password`,同名CLI推动 它在下面。 它在下面.

代码与AWS相同. 全权证书以下列方式解决: `DefaultAzureCredential` (单位:千美元)`az login`,管理身份,或环境变量:

```typescript
import { Envilder } from '@envilder/sdk';

await Envilder.load('envilder.json');

console.log('DB_PASSWORD loaded:', !!process.env.DB_PASSWORD);
```

### 流利的构建器( 有覆盖)

覆盖地图文件 `$config` 运行时间: 用于切换提供者, 配置文件或每个环境的库 URL :

```typescript
import { Envilder, SecretProviderType } from '@envilder/sdk';

// Override provider + vault URL
const secrets = await Envilder.fromMapFile('envilder.json')
  .withProvider(SecretProviderType.Azure)
  .withVaultUrl('https://my-vault.vault.azure.net')
  .resolve();

// Override AWS profile and inject
await Envilder.fromMapFile('envilder.json')
  .withProfile('staging')
  .inject();
```

### 基于环境的装载

基于您当前环境的路径秘密加载 。 每个环境 地图到自己的机密文件(或 `null` 以跳过加载 :

```typescript
import { Envilder } from '@envilder/sdk';

const env = process.env.APP_ENV ?? 'development';

// Resolve + inject into process.env
await Envilder.load(env, {
  production: 'prod-secrets.json',
  development: 'dev-secrets.json',
  test: null, // no secrets loaded
});
```

解决不注射:

```typescript
const secrets = await Envilder.resolveFile(env, {
  production: 'prod-secrets.json',
  development: 'dev-secrets.json',
  test: null,
});
```

行为:

-   如果环境映射到文件路径,则从该文件中载入机密.
-   如果环境映射到 `null` 或不是在地图中,是空的 `Map` 默默返回.
-   空或仅白空的环境名称 `Error`。 。 。 .

### 秘密验证

Opt- in 验证确保所有解密都有非空值 :

```typescript
import { Envilder, validateSecrets } from '@envilder/sdk';

const secrets = await Envilder.resolveFile('envilder.json');
validateSecrets(secrets); // throws SecretValidationError if any value is empty
```

`validateSecrets()` 检查:

-   地图不是空的( 扔出) `SecretValidationError` 带空 `missingKeys`(中文(简体) )
-   每个值都是非空( 扔出) `SecretValidationError` 列出失败的密钥)
-   当所有值都存在时悄悄通过

```typescript
import { SecretValidationError, validateSecrets } from '@envilder/sdk';

try {
  validateSecrets(secrets);
} catch (err) {
  if (err instanceof SecretValidationError) {
    console.log(`Missing: ${err.missingKeys.join(', ')}`);
  }
}
```

### 地图文件合同验证

在装入任何文件前, 请检查地图文件是否有效 与当前证书一起存在被宣布的秘密。 没有使用秘密值 或返回。 这是相同的支票 `envilder validate` 在CLI中.

```typescript
import { Envilder } from '@envilder/sdk';

const result = await Envilder.fromMapFile('envilder.json').validateContract();

if (!result.isValid) {
  for (const error of result.mapFileErrors) {
    console.error(`${error.key}: ${error.message}`);
  }
  for (const key of result.keys.filter((k) => k.status !== 'exists')) {
    console.error(`${key.variable} (${key.provider} ${key.path}): ${key.status}`);
  }
}
```

`validateContract()` 从未为预期的失败投出 结果:

-   `mapFileErrors`: 地图文件不匹配 [已出版计划](https://envilder.com/schema/map-file.v1.json) 或编号 提供者配置无法工作( 例如 ) `vaultUrl` 与AWS). 何时 没有,没有提供商呼叫和 `keys` 为空.
-   `keys`: 每个变量有一个条目 `path`, (中文(简体) ), `provider` 财务报告和审定财务报表 `status`数字 : `exists`, (中文(简体) ), `missing`, (中文(简体) ), `access_denied` (身份无法检查秘密), 从未报告为 `missing`, (中文(简体) ), `authentication_failed` 或者说 `provider_error`。 。 。 . `reason` 当提供商给出一个时,解释最后三个.

在合同未履行时未能完成负载,请选择建筑商。 这个 在解析和丢弃前检查一次 `ContractValidationError`,其 消息命名失败的密钥和路径( 绝不是其值) `result` 掌握全部结果:

```typescript
await Envilder.fromMapFile('envilder.json')
  .withContractValidation()
  .inject(); // throws ContractValidationError if a key is missing
```

无 `withContractValidation()`,负载不会增加提供者呼叫和 不需要额外的许可 。 检查需要 `ssm:GetParameters` 关于AWS( 它 用途 `GetParameters` 分批 10 个 `WithDecryption: false`; 平面 `String` 值仍然可以在反应中返回并被丢弃 与 `kms:Decrypt` 相同的权限读取已解密的值, 所以范围 喜欢 `ssm:GetParameter`和, 打开 Azure 键断层 `List` 秘密许可(进入政策)或 `Microsoft.KeyVault/vaults/secrets/readMetadata/action` (Azure RBAC,列入 ),因为它列出了秘密元数据而不是 读取值.

合同的审定和 `validateSecrets()` 回答不同的问题: 合同验证检查地图文件是否有效, 并宣布每个机密 在解决之前存在; `validateSecrets()` 检查已经存在的值 解决不是空的.

### 高级用途

执行 `ISecretProvider` 插入自定义后端的接口 (例如,HashiCorp Vault,GCP秘密经理):

```typescript
import {
  EnvilderClient,
  MapFileParser,
  type ISecretProvider,
} from '@envilder/sdk';
import { readFileSync } from 'node:fs';

class MyCustomProvider implements ISecretProvider {
  async getSecrets(names: string[]): Promise<Map<string, string>> {
    // fetch from your custom backend
    return new Map();
  }
}

const json = readFileSync('envilder.json', 'utf-8');
const mapFile = new MapFileParser().parse(json);

const provider = new MyCustomProvider();
const client = new EnvilderClient(provider);
const secrets = await client.resolveSecrets(mapFile);
EnvilderClient.injectIntoEnvironment(secrets);
```

### 在流畅的构建器中自定义提供者

`withSecretProvider()` 将构建者交给您自己的提供者实例而不是 它会建造 从 `$config`。地图文件仍然被验证为 常规,所以这也是测试您的启动代码与内存的方法 假,没有云账户、模拟器或环境变量:

```typescript
import {
  Envilder,
  type ISecretExistenceChecker,
  type ISecretProvider,
} from '@envilder/sdk';

const fakeSecrets = new Map([['/app/db-url', 'postgres://localhost/test']]);

class InMemoryProvider implements ISecretProvider, ISecretExistenceChecker {
  async getSecrets(names: string[]): Promise<Map<string, string>> {
    return new Map(
      names.flatMap((name) => {
        const value = fakeSecrets.get(name);
        return value === undefined ? [] : [[name, value] as const];
      }),
    );
  }

  async checkSecretsExist(names: readonly string[]) {
    return new Map(
      names.map((name) => [
        name,
        { status: fakeSecrets.has(name) ? 'exists' : 'missing' } as const,
      ]),
    );
  }
}

await Envilder.fromMapFile('envilder.json')
  .withSecretProvider(new InMemoryProvider())
  .withContractValidation()
  .inject();
```

为了参与合同验证,供应商还执行 `ISecretExistenceChecker`。只执行的提供者 `ISecretProvider` 仍然可以解开秘密,但是 `validateContract()` 每个密钥报告为 `provider_error`这样 `withContractValidation()` 负载失败 。 这个 `provider` 每个密钥的字段保留所配置的类型(`withProvider()`, (中文(简体) ), 接下来 `$config.provider`,则 `aws`) (中文(简体) ).

对于一个完整的,可运行的走过,看 [`typescript-custom-provider`](https://github.com/macalbert/envilder-examples/tree/main/typescript-custom-provider) 缩写中:一个本地AES-256-GCM加密的自定义供应商 文件,带有加载的测试,启动时失败于缺失的秘密,以及 验证合同而不解密任何东西.

## API 参考

### 静态外观`Envilder`(中文(简体) )

| 方法 | 说明 |
| --- | --- |
| `load(path)` | 解密并输入 `process.env` |
| `resolveFile(path)` | 解密, 返回为 `Map<string, string>` |
| `load(env, mapping)` | 以环境为基础的决心+注入 |
| `resolveFile(env, mapping)` | 以环境为基础的决心 |
| `fromMapFile(path)` | 返回配置的流利构建器 |

### 流利的建设者(通过) `fromMapFile()`(中文(简体) )

| 方法 | 说明 |
| --- | --- |
| `withProvider(type)` | 覆盖秘密提供者(AWS/Azure) |
| `withProfile(name)` | 覆盖命名为 AWS 的配置文件 |
| `withVaultUrl(url)` | 覆盖 Azure 密钥断层 URL |
| `withSecretProvider(provider)` | 自己来 `ISecretProvider` 而不是从 `$config` |
| `withContractValidation()` | 在解决前检查一次地图文件合同; 失败 `ContractValidationError` |
| `validateContract()` | 检查地图文件合同并返回 a `ContractValidationResult`未加载 |
| `resolve()` | 解密, 返回为 `Map` |
| `inject()` | 解析 + 注入 `process.env` |

### 验证

| 函数 | 说明 |
| --- | --- |
| `validateSecrets(map)` | 掷出 `SecretValidationError` 如果任何值为空或映射为空 |

## 映射文件格式

```json
{
  "$schema": "https://envilder.com/schema/map-file.v1.json",
  "$config": {
    "provider": "aws",
    "profile": "my-profile"
  },
  "DB_PASSWORD": "/app/prod/db-password",
  "API_KEY": "/app/prod/api-key"
}
```

支助提供者: `aws` (违约), `azure`。 。 。 .

对Azure, 添加 `vaultUrl`数字 :

```json
{
  "$schema": "https://envilder.com/schema/map-file.v1.json",
  "$config": {
    "provider": "azure",
    "vaultUrl": "https://my-vault.vault.azure.net"
  },
  "DB_PASSWORD": "myapp-prod-db-password",
  "API_KEY": "myapp-prod-api-key"
}
```

### 关键和价值

密钥遵循与CLI和GitHub Action相同的规则,所以一个接受的密钥被大家接受:

-   **密钥** 可能只包含字母,数字, `_`, (中文(简体) ), `.`, (中文(简体) ), `-` 财务报告和审定财务报表 `/` (单位:千美元)`^[A-Za-z0-9_./-]+$`(三); `__proto__` 也被拒绝. `MapFileParser.parse` 掷出 `Error` 在获取任何秘密之前. `/` 允许使用等级名称(`Database/Password`),并按原样返回.
-   **数值** 是提供者中的秘密标识符( SSM 参数名称或密钥默认密钥) 名字),必须是JSON字符串.
-   **秘密内容** 以提供者存储的方式返回. `resolveFile` 编号 : `resolve` 让他们进去 记忆; `load` 编号 : `inject` 将其写入操作系统无法操作的进程环境 存储 `NUL` (单位:千美元)`U+0000`)和Windows将变量限制为32,767个字符.

见 [关键和价值:接受什么](https://github.com/macalbert/envilder#keys-and-values-what-is-accepted) 充分参考和解释规则.

见 [根读取](https://github.com/macalbert/envilder#%EF%B8%8F-mapping-file-format) 用于完整地图文件参考.

## 实例

可运行的项目 [阴道模拟器](https://github.com/macalbert/envilder-examples) 解析映射文件 与 AWS SSM 和 Azure 密钥 Vault 相对应(由 localStack 为 AWS 和 LocalStack 为 Azure 组成),并将数值传递到 容器,无 `.env` 文件 :

-   [键入脚本测试容器](https://github.com/macalbert/envilder-examples/tree/main/typescript-testcontainers): 测试容器
-   [键入脚本](https://github.com/macalbert/envilder-examples/tree/main/typescript-aspire): Aspire 类型脚本 AppHost

## 链接

-   [更改日志](https://github.com/macalbert/envilder/blob/main/docs/changelogs/sdk-nodejs.md)
-   [官方网站](https://envilder.com/docs/sdks/nodejs/?utm_source=npm&utm_medium=readme&utm_campaign=sdk)

## 常见问题

### @envilder/sdk 是什么？

从 AWS SSM 参数存储器或 Azure 密钥断层直接装入您的节点\.js 进程——不需要\.env 文件\.

### 如何安装 @envilder/sdk？

在项目目录运行 npm install @envilder/sdk，或使用 pnpm add / yarn add / bun add。

### @envilder/sdk 支持 TypeScript 吗？

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

### @envilder/sdk 支持 ESM 还是 CommonJS？

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

### @envilder/sdk 需要什么版本的 Node\.js？

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

### @envilder/sdk 可以商用吗？

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

### @envilder/sdk 的下载量有多少？

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

### @envilder/sdk 还在维护吗？

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