# @gaia-framework/config 中文文档

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

版本：0\.3\.1
npm 元数据更新时间：2026-11-10T00:59:55.047Z
中文译文更新时间：2026-11-15T21:04:42.852Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：330 kB，202 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：3 个
- 首次发布：2026-10-16T15:22:17.134Z
- 最新版本发布：2026-11-10T00:59:54.841Z
- 近 30 天下载量：3341（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

同步分层的YAML/TOML配置与环境覆盖,指令和计划验证.

## 安装

```sh
npm install @gaia-framework/config
```

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

## README

# @gaia-框架/配置

为 Node.js 应用程序同步配置:分层的 YAML 或 TOML 文件, 环境覆盖、可重复使用的文件碎片、可选 Zod 校验,以及 键入取取器。 用普通对象使用它,将文件加载到读取器中,或绑定 应用程序的 DI 容器中的配置服务 。 图书馆没有 运行时间依赖容器或装饰元数据.

-   顺序文件层和清晰 `--config` 选择.
-   深对象合并、阵列替换和清晰 `null` 数值.
-   环境占地者,倒置者,出逃者,和一键重置者.
-   `$env`, (中文(简体) ), `$file`,以及 YAML/JSON/TOML 数据 `$include` 带有片段选择的指令.
-   必需的和可选的获取器、 字形密钥路径和密钥计数 .
-   可选的严格输入检查、孤立的环境、不可改变的快照和 安全错误.
-   TypeScript申报和汇编无害环境管理出口.

图书馆持有麻省理工学院许可证. 软件包档案包括来源、已编译的导出、, 宣言、文件和实例.

私下报告脆弱性 [警卫](https://npmcn.com/package/%40gaia-framework/config/SECURITY.md)。 。 。 .

## 所需资源

节点.js **24个或较新**,包含无害环境管理进口。 CI 验证 Windows 上的节点 24 和 莱纳克. 普通消费者运行编译的 JavaScript 不使用 `tsx` 或特别 节点条件. 没有提供普通JS和浏览器构建.

## 支助范围

自动发现默认为 `.yaml`; 选择 `fileFormat: 'toml'` 页:1 `.toml` 层。 包括支助 `.yaml`, (中文(简体) ), `.yml`, (中文(简体) ), `.json` 财务报告和审定财务报表 `.toml`,包括混合格式 锁链。 没有远程加载,监视器,也没有Aync API. 见 [移动](https://npmcn.com/package/%40gaia-framework/config/docs/toml.md)。 。 。 . 导入库不装入 `.env` 文档.

## 安装

在应用程序中安装软件包 :

```sh
npm install @gaia-framework/config
```

或与雅尔曰:

```sh
yarn add @gaia-framework/config
```

Zod是可选的。 单独安装 `yarn add zod` 如果您的申请 使用Zod schemas(英语:Zod schemas).

### 构建本地归档

如果 `yarn` 命令未安装, 将它安装到全球一次 :

```sh
npm install -g yarn
```

在这个仓库里, `yarn` 使用已检查的 Yarn 4.1.20. 运行时间 `.yarnrc.yml`现有由核心软件包管理 `yarn` 命令也会起作用.

要通过退票建立归档, 您可以访问 :

```sh
git clone https://github.com/gaia-framework/config.git
cd config
yarn install --immutable
yarn build
yarn pack --out artifacts/gaia-framework-config-0.3.1.tgz
```

将生成的归档复制到您的应用程序目录中, 然后安装 :

```sh
yarn add ./gaia-framework-config-0.3.1.tgz
```

档案包括已汇编的出口、申报、发展来源、文件、, 实例和许可证。 它的工作独立于这个检查.

## 快开始

另存为 `app.ts` 在应用程序中运行 `node app.ts`数字 :

```js
import { createConfig } from '@gaia-framework/config';

const config = createConfig({
  http: { port: 4001 },
  feature: { enabled: true },
  providers: ['local']
});

console.log(config.getNumber('http.port')); // 4001
console.log(config.getBoolean('feature.enabled')); // true
console.log(config.getStringArray('providers')); // ['local']
console.log(config.getOptionalString('http.host') ?? 'localhost'); // localhost
```

### 装入 YAML 文件

创建 `config.yaml` 在应用程序的工作目录中 :

```yaml
http:
  host: ${APP_HOST:-localhost}
  port: 4001
feature:
  enabled: ${APP_FEATURE_ENABLED:-false}
```

替换 `app.ts` 改为:

```js
import { createConfigFromFiles } from '@gaia-framework/config';

const config = createConfigFromFiles({ argv: [] });

console.log(config.getNumber('http.port')); // 4001
console.log(config.getString('http.host')); // localhost when APP_HOST is unset
console.log(config.getBoolean('feature.enabled')); // false when unset
```

`argv: []` 禁止检查应用程序的命令行参数. 让它接受重复 `--config <file>` 参数,例如 `node app.ts --config base.yaml --config deployment.yaml`替换选中的文件 自动发现并按参数顺序合并.

### 装入 TOML 文件

创建 `config.toml`数字 :

```toml
[http]
port = 4001
host = "${APP_HOST:-localhost}"

[feature]
enabled = "${APP_FEATURE_ENABLED:-false}"
```

明确选择 TOML 发现 :

```js
const config = createConfigFromFiles({ fileFormat: 'toml', argv: [] });
console.log(config.getNumber('http.port')); // 4001
```

在解析后适用相同的环境、合并、指令和计划规则. 必须引用TOML日期,引用不安全的整数,以及 `{ "$null" = true }` 清除继承的值。 见 [TOML 指南](https://npmcn.com/package/%40gaia-framework/config/docs/toml.md) 财务报告和审定财务报表 [可运行的示例](https://npmcn.com/package/%40gaia-framework/config/examples/13-toml/README.md)。 。 。 .

## 装入顺序和合并

自动发现合并了以下文件,以后的值优先 :

| 顺序 | 文件或覆盖 |
| --- | --- |
| 1个 | `config.yaml` |
| 2个 | `config.{environment}.yaml` |
| 3个 | `config.local.yaml` |
| 页:1 | `config.{environment}.local.yaml` |
| 页:1 | 全对象 `CONFIG` 环境覆盖 |
| 6个 | 按键 `CONFIG_*` 环境覆盖 |
| 第7条 | 应用计划验证、默认和转换 |

与 `fileFormat: 'toml'`,同样的四个发现层 `.toml` 换句话说.

目录来自 `basePath`,则 `CONFIG_DIR`,则 `process.cwd()`。 。 。 . 环境来自 `envName`,则 `CONFIG_ENV`,则 `NODE_ENV`,则 `development`。这些名称和 `config` 文件名前缀可配置 .

对象递归合并;数组和平面取代更早的值. `null` 清除一个值,同时 `undefined` 无法推翻它。 缺少发现层 是可选的。 丢失的显性文件也默认被跳过; 启用 `strictFiles: true` 要求他们。 见 [文件加载](https://npmcn.com/package/%40gaia-framework/config/docs/loading.md)。 。 。 .

## 环境覆盖和占位符

一个明确的环境图使这个例子独立于 shell 语法:

```js
import { loadConfigObjectFromFiles } from '@gaia-framework/config';

const config = loadConfigObjectFromFiles({
  argv: [],
  inheritProcessEnv: false,
  env: {
    CONFIG: '{"http":{"host":"example.test","port":4001}}',
    CONFIG_http_port: '5000'
  }
});

console.log(config.http.port); // 5000
console.log(config.http.host); // example.test
```

`CONFIG` 一定是JSON的对象 每键值尽可能被解析为JSON, 数字、布尔、数组、对象和 `null` 能够覆盖文件值. 名称对大小写敏感: `CONFIG_http_port` 目标 `http.port`, (中文(简体) ), `__` 编码 字形下划线,以及 `___` 编码连字符.

在YAML内部, `${NAME}` 需要非空变量; `${NAME:-fallback}` 用品 倒计时 `$${NAME}` 保留文字 `${NAME}`整个占位符 带有 `true` 或者说 `false` fallback 生成布尔并验证该词汇. 数字占位符仍然是字符串,直到一个得到的或计划转换它们.

默认提供 `env` 地图取代用于发现和 覆盖,但占位符和 `$env` 仍然可以回到单个进程 变量。 设定 `inheritProcessEnv: false` 完全隔离。 见 [环境变量](https://npmcn.com/package/%40gaia-framework/config/docs/environment.md) 用于逃跑,空值,编码, 和确切的优先权规则.

## 包括和提交指令

指令是完全有一个键和一个字符串参数的对象:

```yaml
label: { $env: APP_LABEL }
message: { $file: ./message.txt }
service: { $include: ./parts/service.yaml }
firstItem: { $include: "./parts/items.json#items.0" }
```

`$env` 读取所需的字符串. `$file` 逐字读取 UTF-8 文本. `$include` 解析YAML、JSON或TOML,并解决嵌入式占位符和指令。 相对 路径从包含指令的文件开始; 片段选择嵌入 对象属性或数组元素。 循环被拒绝并重复 每个装入器被缓存。 使用信任的配置文件: 指令可以读取 用于节点进程的路径.

这个 [指令指南](https://npmcn.com/package/%40gaia-framework/config/docs/directives.md) 解释碎片、错误、相对 路径和缓存寿命. [实例05](https://npmcn.com/package/%40gaia-framework/config/examples/05-directives/README.md) 包含 所有需要的固定文件和预期结果.

## Schema 验证

验证是可选的。 如果您的应用程序使用Zod,请明确安装:

```sh
yarn add zod
```

提供同步 Zod 计划以验证、应用默认值并转换值:

```js
import { z } from 'zod';
import { createConfig } from '@gaia-framework/config';

const schema = z.object({
  port: z.coerce.number().int().positive(),
  enabled: z.boolean().default(true)
});
const config = createConfig({ port: '4001' }, schema);

console.log(config.getNumber('port')); // 4001
console.log(config.getBoolean('enabled')); // true
```

Zod 是此寄存器的开发依赖, 而不是运行时间或同行依赖 图书馆。 应用程序选择自己的 Zod 版本; 自定义同步 策略可以执行导出 `ConfigSchema<T>` 界面。 对于文件, 通过 `schema` 到文件厂;在装入、解析、合并后运行,以及 环境覆盖. `loadConfigLayersFromFiles(options)` 返回生层 即使选项中存在一个.

没有提供的计划,就没有具体的计划验证或应用程序 默认 。 验证失败 。 Async schemas是不支持的. 见 [鉴定和设计](https://npmcn.com/package/%40gaia-framework/config/docs/validation-and-di.md)。 。 。 .

## 阅读器、服务和打入器

`createConfig` 财务报告和审定财务报表 `createConfigFromFiles` 返回 a `ConfigReader`。 。 。 . `createConfigService` 财务报告和审定财务报表 `createConfigServiceFromFiles` 返回 a `ConfigService` 具有相同的获取界面.

| 需要的获取 | 可选对应方 | 目的 |
| --- | --- | --- |
| `get<T>(path)` | `getOptional<T>(path)` | 使用呼叫者提供的类型断言读取一个值 |
| `getString(path)` | `getOptionalString(path)` | 需要一个字符串 |
| `getNumber(path)` | `getOptionalNumber(path)` | 读取数字或转换数值 |
| `getBoolean(path)` | `getOptionalBoolean(path)` | 读取布尔或公认的布尔字符串 |
| `getStringArray(path)` | `getOptionalStringArray(path)` | 需要字符串数组 |

缺少需要的获取器投掷或 `null` 值和输入的获取器拒绝 无效的值 。 可选获取器返回 `undefined` 失踪/`null` 数值; 可选的已键获取器也返回 `undefined` 用于普通类型不匹配. 默认数字转换跟随 JavaScript `Number`;布尔获取器接受 `true/false`, (中文(简体) ), `1/0`, (中文(简体) ), `yes/no`,以及 `on/off` 字符串不修剪白空间. 在需要更窄的转换时使用严格的获取器.

每一个得到和 `has(path)` 接受点字符串或字段数组. 譬如说, `getString(['literal.name'])` 读取单个点化属性,同时 `getString('literal.name')` 穿行有二个属性. 数字段访问数组 要素. `keys()` 列出捕获到的点形密钥; `keyPaths()` 返回防御状态 复制清晰的线段数组。 花序为盘点时的叶片.

普通的获取类型是断言,而不是计划引出路径或运行时间 审定。 见 [API 参考](https://npmcn.com/package/%40gaia-framework/config/docs/api.md) 每个导出、 选项、 默认, 和错误合同.

## 缓存和选择性更严格的行为

`createConfigServiceFromFiles` 用于同等装载选项的再利用服务, 环境快照 和计划特征. **仅更改文件内容 不使缓存无效.** 过 `cache: false` 每次读取新文件. `createConfigFromFiles` 而对象加载功能不重复使用服务. 重新使用 a `ConfigLoader` 也包括缓存; 构造新的加载器 包括新鲜的.

读者缓存查找并获取其在构建时的关键索引. 照顾他们 数据在构建后保持稳定。 默认值可以共享可变对象/阵列 参考资料; `immutable: true` 反而制造出一个脱开的 深冻的快照 经计划处理后支持的纯数据.

| 选项 | 启用时的效果 |
| --- | --- |
| `strictFiles` | 需要明确选择的文件和有效文件 `--config` 参数 |
| `strictGetters` | 需要有限的数字输入、严格的布尔字符串和密集的字符串数组 |
| `strictPaths` | 拒绝空路段和非奇异数组索引 |
| `inheritProcessEnv: false` | 禁用默认进程环境 |
| `safeErrors` | 返回固定消息 `ConfigError` 代码没有原始错误原因 |
| `immutable` | 将支持的数据复制到深冻的阅读器快照中 |
| `cache: false` | 旁通服务再利用于 `createConfigServiceFromFiles` |

严格检查、安全错误和不可改变的快照默认被禁用; 启用环境继承和文件服务缓存。 档案厂拿 这些选项直接。 记忆工厂把读者选择作为第三个 参数,在可选方案之后。 见 [API 参考](https://npmcn.com/package/%40gaia-framework/config/docs/api.md#in-memory-inputs-and-option-placement) 选择位置, [严格的获取器](https://npmcn.com/package/%40gaia-framework/config/docs/api.md#strict-getters), (中文(简体) ), [安全错误](https://npmcn.com/package/%40gaia-framework/config/docs/api.md#safe-errors),以及 [快照](https://npmcn.com/package/%40gaia-framework/config/docs/api.md#immutable-snapshots)。 。 。 . 这个 [装入指南](https://npmcn.com/package/%40gaia-framework/config/docs/loading.md) 覆盖解析深度和缓存寿命 .

## 使融合无效

安装 `inversify` 财务报告和审定财务报表 `reflect-metadata` 在应用程序中绑定读取器 明确构建普通服务:

```js
import 'reflect-metadata';
import { Container } from 'inversify';
import { ConfigReader, ConfigService } from '@gaia-framework/config';

const container = new Container();
container.bind(ConfigReader).toConstantValue(new ConfigReader({ port: 4001 }));
container.bind(ConfigService).toDynamicValue((context) =>
  new ConfigService(context.get(ConfigReader))
);

console.log(container.get(ConfigService).getNumber('port')); // 4001
```

声明 `inversify` 财务报告和审定财务报表 `reflect-metadata` 在导入它们的应用程序中. 在装饰类前初始化元数据; 使用 TypeScript 应用程序 装饰者应当保留相应的编译器设置. 见 [鉴定和设计](https://npmcn.com/package/%40gaia-framework/config/docs/validation-and-di.md) 编辑 [可运行的 DI 实例](https://npmcn.com/package/%40gaia-framework/config/examples/07-di/README.md)。 。 。 .

## 文件和实例

| 指南 | 目录 |
| --- | --- |
| [公共 API](https://npmcn.com/package/%40gaia-framework/config/docs/api.md) | 工厂、类别、类型、获取器、默认和出错 |
| [文件装入](https://npmcn.com/package/%40gaia-framework/config/docs/loading.md) | 发现、工作目录、明确文件、合并和缓存 |
| [环境变量](https://npmcn.com/package/%40gaia-framework/config/docs/environment.md) | 覆盖、路径编码、占位符、倒置和逃跑 |
| [指令](https://npmcn.com/package/%40gaia-framework/config/docs/directives.md) | 环境/文本读取、混合格式包括、碎片和周期 |
| [移动](https://npmcn.com/package/%40gaia-framework/config/docs/toml.md) | 明确 TOML 发现、 无效清除、 类型规则和语法 |
| [鉴定和设计](https://npmcn.com/package/%40gaia-framework/config/docs/validation-and-di.md) | 分解处理和反向组成 |
| [可运行示例](https://npmcn.com/package/%40gaia-framework/config/examples/README.md) | 命令、固定文件和所有示例的预期产出 |
| [自定义命名](https://npmcn.com/package/%40gaia-framework/config/examples/08-conventions/README.md) | 明确定制服务和平台命名选项 |
| [内部结构](https://npmcn.com/package/%40gaia-framework/config/docs/architecture.md) | 模块所有权、分辨率上下文、缓存和验证边界 |

对于完整的应用程序示例,请从 [分层服务](https://npmcn.com/package/%40gaia-framework/config/examples/11-service/README.md) 或者说 [模块化加工管道](https://npmcn.com/package/%40gaia-framework/config/examples/12-pipelines/README.md)。每个都有一个匹配 TOML 版本具有相同的解析值并拥有库拥有的合成子图.

使用 [基准](https://npmcn.com/package/%40gaia-framework/config/docs/benchmarking.md) 生成您自己的计时表 工作量。 结果属于被忽略的文物或CI文物;不是 (c) 实施每台机器的快照或普遍履约保证.

## 发展和核查

使用节点 24 从寄存器根运行下面的命令 。 跟着 [安装步骤](https://npmcn.com/package/%40gaia-framework/config/#readme-installation) 将制作 `yarn` ,然后确认 `yarn --version` 报告 `4.12.0` 在退票内.

维护实例、工具、测试和配置使用 `.ts` 来源. 运行示例 直接与节点 24 (`node index.ts` (从他们的文献目录中)。 类型检查 覆盖实例和工具; 独立的软件包检查也验证实例 对照已安装的申报并执行编译的 JavaScript 消费者固定装置.

| 命令 | 目的 |
| --- | --- |
| `yarn lint` | 格式化、ESLint和Markdown/例检查 |
| `yarn typecheck` | 检查类型脚本而不排放输出 |
| `yarn test` | 单位、整合和回归测试 |
| `yarn test:coverage` | 编译的试验和生产范围 |
| `yarn build` | 编译制作 JavaScript 和声明 |
| `yarn test:examples` | 运行每个文件示例; 先构建 |
| `yarn test:package` | 构建、包装和核实一次性独立消费者 |
| `yarn validate` | 运行上面的全部序列 |
| `yarn benchmark:smoke` | 检查没有速度阈值的合成基准固定装置 |
| `yarn benchmark` | 运行完整的合成计时套件 |
| `yarn benchmark:traversals` | 测量图表保护、计划处理、快照、索引编制和工厂建设 |

CI 运行 Windows 和 Linux 上的全部验证和基准烟雾 推动和拉取请求,包括没有PR的特征分支. 特性推 当 PRCI 已经覆盖同一承诺时, 跳过重复验证 。 主推车 运行共享检查通过 `publish.yml`即使没有版本起伏. 新更新取消已取代的功能分支或 PR 运行; 主承诺保留其 自行审定和发放批准. 包接收比较 npm/ Yarn 存档内容, 验证许可证, 检查 汇编进口和申报,进行发展出口和开发,以及 运行出账外的示例。 测试使用合成数据和一次性数据 文档。 覆盖范围写给 `coverage/`; 向 `artifacts/`。 。 。 . 见 [捐款](https://npmcn.com/package/%40gaia-framework/config/CONTRIBUTING.md) 编辑 [更改日志](https://npmcn.com/package/%40gaia-framework/config/CHANGELOG.md)。 。 。 .

## 释放

合并高点 `package.json` 版本为 `main` 于 Linux/ Windows 验证并需要维护者批准. 工作流程发布 到 npm, 验证已安装的软件包, 然后创建匹配的 GitHub 释放 带有生成的注释和已验证的归档。 其他合并只运行验证 . 手动干燥和回收仍然可用。 叉可以验证但不能 继承出版权限。 见 [发布指南](https://npmcn.com/package/%40gaia-framework/config/docs/releasing.md)。 。 。 .

## 许可证

[麻省理工学院](https://npmcn.com/package/%40gaia-framework/config/LICENSE) (原始内容存档于2026 Gaia-框架). 属地保留自己的许可证.

## 常见问题

### @gaia-framework/config 是什么？

同步分层的YAML/TOML配置与环境覆盖,指令和计划验证\.

### 如何安装 @gaia-framework/config？

在项目目录运行 npm install @gaia-framework/config，或使用 pnpm add / yarn add / bun add。

### @gaia-framework/config 支持 TypeScript 吗？

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

### @gaia-framework/config 支持 ESM 还是 CommonJS？

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

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

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

### @gaia-framework/config 可以商用吗？

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

### @gaia-framework/config 的下载量有多少？

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

### @gaia-framework/config 还在维护吗？

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