# @bedrock/config-yaml 中文文档

规范地址：https://npmcn.com/package/%40bedrock/config-yaml/

版本：4\.7\.0
npm 元数据更新时间：2026-10-12T14:56:10.738Z
中文译文更新时间：2026-11-07T20:38:46.800Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40bedrock/config-yaml
原文对照：https://npmcn.com/package/%40bedrock/config-yaml/?lang=original
项目主页：https://github.com/digitalbazaar/bedrock-config-yaml
源码仓库：https://github.com/digitalbazaar/bedrock-config-yaml

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

- 包体积（解压后）：67.2 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：1 个
- peer 依赖：@bedrock/core ^6\.3\.0
- 首次发布：2022-04-04T15:38:34.569Z
- 最新版本发布：2026-10-12T14:56:10.540Z
- 近 30 天下载量：3532（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 4 个）

## 中文简介

贝德洛克配置 YAML

## 安装

```sh
npm install @bedrock/config-yaml
```

也可以使用：`pnpm add @bedrock/config-yaml`、`yarn add @bedrock/config-yaml`、`bun add @bedrock/config-yaml`

## README

# Bedrock YAML 配置 _(@bedrock/config-yaml)_

此模块将 YAML 配置合并到 `bedrock.config`. YAML 值 可以在应用程序模块配置后添加或覆盖值 贝德洛克 配置可以来自文件、环境变量或函数 由申请注册.

在没有环境配置或活动注册源的情况下,Bedrock读取 已配置 YAML 文件 。 如果这些文件丢失,则继续启动 应用程序的配置.

## 安装

这个软件需要并支持维持了最新版本的Node.js. 更新可能会去除对旧的未维护的平台版本的支持. 请使用 依赖版本锁定文件和测试以确保与此兼容 软件.

### 国家预防机制

通过国家预防机制安装:

```
npm install --save @bedrock/config-yaml
```

### 发展

在当地安装(用于开发):

```
git clone https://github.com/digitalbazaar/bedrock-config-yaml.git
cd bedrock-config-yaml
npm install
```

## 使用量

为了确保没有其他模块能够推翻YAML配置, `bedrock-config-yaml` 应该是上次导入 `bedrock.start()` 实值 电话 若为 `bedrock-config-yaml` 不是最后一个 `bedrock-cli.parsed` 或者说 `bedrock.configure` 事件处理器,将丢出一个可以防止 应用程序启动.

不同时应用两个独立的配置文件 bedrock 启动期间发生的事件 : `core` 财务报告和审定财务报表 `app`。 。 。 .

### 核心配置

这个 `core` 配置用于配置核心贝德罗克特性,例如: 工人人数或默认的日志。 这个 `core` 配置应用于 最后一个处理器 `bedrock-cli.parsed` 活动。 默认位置 页:1 `core` 配置为 : `/etc/bedrock-config/core.yaml`。 。 。 .

#### 样本 `core.yaml`

```yaml
core:
  workers: 2
loggers:
  console:
    bedrock:
      formatter: logstash
```

### App 配置

这个 `app` 配置用于配置 Bedrock 应用程序/模块特性. 这个 `app` 配置由最后一个处理器应用 `bedrock.configure` 活动。 默认位置 `app` 配置为 : `/etc/bedrock-config/app.yaml`。 。 。 .

#### 样本 `app.yaml`

```yaml
test-bedrock-module:
  foo: fromYaml
  overwriteMe: fromYaml
another-bedrock-module:
  host: example.com
  port: 18443
```

### 从环境变量装入

可以装入配置 YAML 从一个 `BEDROCK_CONFIG` 环境 变量。 该值是整个YAML配置文件的基数64编码版本. 如果找到此变量, 将跳过基于文件系统配置设置 .

### 从压缩环境变量装入中

配置 YAML 也可以从 `BEDROCK_CONFIG_GZIP` 环境 变量。 值是整个 YAML 配置文件, gzipped 和 碱基64 已编码。 当配置被存储在有大小限制的地方时,这个是有用的, 例如AWS保密管理器秘密,将存储值限制在64 KB; YAML和PEM文本一般由大约3-4x压缩.

要产生一个值:

```
gzip -c config.yaml | base64
```

检查一个:

```
echo "$BEDROCK_CONFIG_GZIP" | base64 -d | gunzip
```

只有一个 `BEDROCK_CONFIG_GZIP` 或者说 `BEDROCK_CONFIG` 可能设定。 设置两者 模棱两可,启动时失败,而不是默默地忽略其中之一.

严格解码值:如果 `BEDROCK_CONFIG_GZIP` 设置但无效 gzip, a 启动失败 `BEDROCK_CONFIG_GZIP is invalid` 错误而不是 倒计时 `BEDROCK_CONFIG`时 `BEDROCK_CONFIG_GZIP` 是未设置的, `BEDROCK_CONFIG` 补给基地64编码为YAML.

## 配置来源

一个应用程序可以注册一个能加载其合并的YAML配置的函数. 导入 `@bedrock/config-yaml` 在调用前最后并注册该函数 `bedrock.start()`数字 :

```js
import * as bedrock from '@bedrock/core';
import {readFile} from 'node:fs/promises';

// import application modules here

// load YAML after the application's configuration handlers
import {addConfigurationSource} from '@bedrock/config-yaml';

addConfigurationSource({
  name: 'deployment',
  getConfig: async () => readFile('/etc/deployment.yaml', 'utf8')
});

bedrock.start();
```

`name` 必须是独特的 `getConfig` 必须是函数。 函数返回 YAML 带一个 `core` 节,a `app` 或两者兼有:

```yaml
core:
  core:
    workers: 1
app:
  server:
    port: 8080
```

每个功能在启动期间每个进程都称为一次. 贝德洛克在等着 函数,并对两个配置事件使用相同的解析文档. 适用 `core` 期间 `bedrock-cli.parsed` 财务报告和审定财务报表 `app` 期间 `bedrock.configure`。配置值变压器在这些部分工作.

来源按登记顺序合并。 后续源覆盖匹配 来自早先来源的数值。 返回时 `null` 或者说 `undefined` 以跳过源代码. 如果全部来源被跳过, Bedrock 将载入配置的 YAML 文件 。 如果有的话 `BEDROCK_CONFIG` 或者说 `BEDROCK_CONFIG_GZIP` 设定, Bedrock 使用该环境 不调用注册来源的配置 .

在配置加载前注册源 。 重复姓名和登记 在加载开始后,会引发错误。 丢出或返回无效的源 YAML停止启动.

## 配置值转换器

配置可以使用 _变压器_, (中文(简体) ), 答复 `$NAME` 键 :

```yaml
database:
  password: {$SECRET: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:db-Ab1'}
  host: {$ENV: DB_HOST}
  port: {$ENV: {name: DB_PORT, type: number, default: 5432}}
```

同样的语法在JSON中有效,因为YAML是其中的一集:

```json
{
  "database": {
    "host": {"$ENV": "DB_HOST"},
    "port": {"$ENV": {"name": "DB_PORT", "type": "number", "default": 5432}}
  }
}
```

指令是一个对象 **仅限** 键为 `$` 然后是大写 变压器的名称。 只保留大写名称,所以 `{$ref: ...}`, (中文(简体) ), `{$schema: ...}`,和 MongoDB 样式 `{$gt: 5}` 仍然是普通配置值。 A 类 指令密钥与其他密钥共享对象是一个错误并失败 负载而不是被默默地视为一个值.

指令在解析后解决,然后合并为 `bedrock.config`,也可能是aync, 这使得远程的外观像 上面的一个可能。 除了内在 `env`,该模块 变压器;应用程序自行提供. 一个没有使用配置的配置被解析 像以前一样合并.

### 启用变形器

变压器必须都是 **登记** 应用代码和 **允许** 以 页:1 `config-yaml.transformers.allow` 相会. 登记通常是一边的 导入的效果; 允许列表是实际打开的变压器 . 默认情况下, 绝不允许 :

```js
import * as bedrock from '@bedrock/core';
// application code that registers `secret`, `ssm`, and `kms-decrypt`
import './lib/aws-transformers.js';
import '@bedrock/config-yaml';

// only these two may be used by a config; `true` allows all registered
bedrock.config['config-yaml'].transformers.allow = ['env', 'secret'];
```

未注册或不允许启动的变压器 作为未解决的对象留在配置中.

可能设置部署配置 `config-yaml.transformers` 本身,所以操作员 可以在不改变应用程序的情况下启用变压器:

```yaml
config-yaml:
  transformers:
    allow: ['env']
```

使用配置符的设置,在同一指令之前使用 配置已解决, a `core` 配置的设置适用于 `app` 配置 跟着它.

因此,登记是安全边界:一个配置只能使 应用程序已经注册的变压器,以及 `env` 是唯一一个 本模块自行登记。 许可列表是操作切换 那个套.

### 内建 `env` 变形器

`$ENV` 读取环境变量。 它是默认注册的,但是,像任何 变压器,必须在允许列表中添加后才能被使用.

```yaml
host: {$ENV: DB_HOST}                        # required; fails if unset
port: {$ENV: {name: DB_PORT, type: number}}  # string, number, boolean, json
debug: {$ENV: {name: DEBUG, type: boolean, default: false}}
```

除非 `type` 被赋予,所以 `{$ENV: WORKERS}` 产量 `"2"`, (中文(简体) ), 没有 `2`。一个没有设置的变量 `default` 失败配置负载而不是 默默地变得 `undefined`。 。 。 .

`$ENV` 让控制配置的人读取 _任意_ 环境变量和 把它放在任何配置中。 缩小范围:

```js
config['config-yaml'].transformers.env.allow = ['DB_HOST', /^MYAPP_/];
```

### 写入变形器

```js
import {registerTransformer, TransformError} from '@bedrock/config-yaml';

registerTransformer({
  name: 'secret',                 // used as `{$SECRET: ...}`
  kinds: ['scalar', 'mapping'],   // value shapes accepted; default: ['scalar']
  async transform({value, path, settings, configType, signal}) {
    return await fetchSecret(value, {signal});
  }
});
```

`transform` 接收指令的值为 `value` 并可以还原任何价值, 包括扩展为配置子树的对象。 它可能是同步或 并必须在 `bedrock.start()` 名为. `settings` 实值 这个变压器自己的配置,从 `config-yaml.transformers.<name>` - 说吧 同一个地方的内置 `env` 读取 `env.allow` 从.

指令可能是嵌入式的,最内向的,所以变压器总是得到 完全解析后输入 :

```yaml
apiKey: {$BASE64: {value: {$SECRET: 'arn:aws:secretsmanager:...:b64-key-Ab1'}}}
```

变形器错误用变形器名称和配置路径报告,永远不要 值; 基本错误记录在 `debug` 换作水平。 A 类 变压器可能抛出一个 `TransformError` 以添加失败的原因, 这必须 不包含配置值或解密:

```
Failed to load config: config transformer "$ENV" at "database.host" requires
the "DB_HOST" environment variable, which is not set
```

### 其他设置

```js
// bounds the whole resolution pass, so a hung lookup fails startup
config['config-yaml'].transformers.timeout = 30000;
// resolve identical directives, e.g. the same secret, once per load
config['config-yaml'].transformers.cache = true;
```

## 许可证

[Apache 许可证,2.0版本](https://npmcn.com/package/%40bedrock/config-yaml/LICENSE) 版权:2011-2026 Digital Bazaar, Inc.

其他贝德罗克图书馆可使用非商业许可证 诸如自学、研究、个人项目或评价目的. 见 [Bedrock 非商业许可证 v1.0](https://github.com/digitalbazaar/bedrock/blob/main/LICENSES/LicenseRef-Bedrock-NC-1.0.txt) 详细情况.

商业许可证和通过联系获得支助 [数字集市](https://digitalbazaar.com/) [支持@ digitalbazaar.com](mailto:support@digitalbazaar.com)。 。 。 .

## 常见问题

### @bedrock/config-yaml 是什么？

贝德洛克配置 YAML

### 如何安装 @bedrock/config-yaml？

在项目目录运行 npm install @bedrock/config-yaml，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@bedrock/core（^6\.3\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bedrock/config-yaml 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bedrock\_\_config-yaml 是否存在。

### @bedrock/config-yaml 支持 ESM 还是 CommonJS？

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

### @bedrock/config-yaml 需要什么版本的 Node\.js？

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

### @bedrock/config-yaml 可以商用吗？

@bedrock/config-yaml 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @bedrock/config-yaml 的下载量有多少？

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

### @bedrock/config-yaml 还在维护吗？

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