# @ekino/config 中文文档

规范地址：https://npmcn.com/package/%40ekino/config/

版本：0\.7\.1
npm 元数据更新时间：2026-07-10T12:46:06.629Z
中文译文更新时间：2026-11-13T10:07:09.869Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：116 kB，21 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2017-06-09T16:05:10.809Z
- 最新版本发布：2026-07-10T12:46:06.355Z
- 近 30 天下载量：12195（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 2 个）

## 中文简介

由yaml提供动力的轻量级配置模块

## 安装

```sh
npm install @ekino/config
```

也可以使用：`pnpm add @ekino/config`、`yarn add @ekino/config`、`bun add @ekino/config`

## README

# @ekino/ 配置

[![NPM version](https://img.shields.io/npm/v/@ekino/config.svg?style=flat-square)](https://www.npmjs.com/package/@ekino/config) [![Coverage Status](https://img.shields.io/coveralls/ekino/node-config/master.svg?style=flat-square)](https://coveralls.io/github/ekino/node-config?branch=master)

一个由Yaml提供动力的轻量级/倾斜型/横向配置模块.

-   [动机](https://npmcn.com/package/%40ekino/config/#readme-motivation)
-   [安装](https://npmcn.com/package/%40ekino/config/#readme-installation)
-   [使用量](https://npmcn.com/package/%40ekino/config/#readme-usage)
    -   [环境变量覆盖](https://npmcn.com/package/%40ekino/config/#readme-environment-variables-override)
    -   [CONF FILES 覆盖](https://npmcn.com/package/%40ekino/config/#readme-conf_files-override)
    -   [继承模式](https://npmcn.com/package/%40ekino/config/#readme-inheritance-model)

## 动机

为什么另一个Node.js配置包?

这是我们在开始这个模块前 问自己一个问题, 我们想要简单的配置管理 具有以下特性:

-   简单使用
-   小脚印
-   同质配置文件格式
-   没有全局/ 特定/ 前配置模块可以装入( 例如需要 lib, 配置它, 然后直接使用软件包 )
-   人类可读性
-   简洁
-   评论
-   类型
-   覆盖
-   信封变量支持

有几个模块已经存在,但是没有一个模块符合我们的要求, 有些过于有限,而另一些则在我们看来非常膨胀.

我们选择了Yaml 因为它会自动满足几个要求, 它比起json简洁,你可以添加注释,它支持类型 读起来非常容易 Yaml还提供其他精致的功能 例如 [锚](http://www.yaml.org/spec/1.2/spec.html#id2765878)。 。 。 .

**我们只支持 Yaml 配置文件**,有一个项目与 `json`, (中文(简体) ), `xml`, (中文(简体) ), `toml`, (中文(简体) ), `ini`, (中文(简体) ), `properties`,只是没有规模 当工作大的项目, 每个人添加它最喜欢的口味.

然后我们用环境变量来加载 覆盖或定义一些特定的密钥, 很容易根据环境来调整你的配置 你跑不动 单行代码甚至配置文件. 严重使用多克时真的很方便.

我们用这个代码跨过几个项目(一个小文件,目前由~100 loc组成), 并在需要时加以改进.

我们到了! 它现在开源 我们希望它能帮助别人 像它为我们所做的那样 造出令人惊叹的东西.

## 安装

使用 pnpm : `pnpm add @ekino/config`

或npm: (中文(简体) ) `npm install @ekino/config`

### 巨钩

此软件包通过设置来配置寄存器的本地 Git 钩 :

`core.hooksPath = ./.githooks`

在安装过程中会自动做到这一点,以确保为贡献者持续启用Git钩.

## 使用量

由于这个模块非常依赖 **环境变量**你可以读 [这个](https://en.wikipedia.org/wiki/Environment_variable) 如果你对她们不满意的话.

默认情况下,本模块假设配置文件位于您当前工作目录的根( Q)`process.cwd()`) (中文(简体) ). 然而,您可以用相对路径或绝对路径在其它任何地方加载文件 :

```

├─ conf/
├─ base.yaml # the base configuration
├─ env_mapping.yaml # defines mapping between env vars and config keys
└─ dev.yaml # Optional file loaded if CONF_FILES includes `dev`

```

`base.yaml` 它定义了您应用程序的共同基本配置.

然后在代码中获取一个配置密钥值 :

```yaml
# /conf/base.yaml
host: base.config.io
external_api:
    key: xxxxx
```

```javascript
// test.js
const config = require('@ekino/config')
console.log(config.get('host'))
console.log(config.get('external_api.key'))
```

如果我们运行这个剧本,我们将有:

```sh
node test.js
> base.config.io
> xxxxx
```

### 环境变量覆盖

有时您想要在特定环境中覆盖一个单一的值, 因此本模块提供 一个特殊文件,名为 `env_mapping.yaml`,它允许根据 环境可变值.

假设有以下配置文件:

```yaml
# /conf/base.yaml
host: base.config.io
external_api:
    key: xxxxx
```

```yaml
# /conf/env_mapping.yaml
HOST: host
API_KEY: external_api.key
```

和以下代码:

```javascript
// test.js
const config = require('@ekino/config')
console.log(config.get('host'))
console.log(config.get('external_api.key'))
```

如果我们运行这个剧本,我们将有:

```sh
node test.js
> base.config.io
> xxxxx

HOST=staging.config.io API_KEY=12345 node test.js
> staging.config.io
> 12345
```

第二次运行输出了不同的值,因为我们绘制了 `HOST` 财务报告和审定财务报表 `API_KEY` 环境变量 页:1 `host` 财务报告和审定财务报表 `external_api.key` 使用配置密钥 `env_mapping.yaml`。 。 。 .

环境变量可能很方便,但是当从节点读到它们时, 我们总是会得到一个字符串, 例如,在处理布尔值时,这可能很烦人. 因此,可以选择性地强制集合环境变量值的类型:

```yaml
# /conf/env_mapping.yaml
PORT:
    key: port
    type: number
USE_SSL:
    key: use_ssl
    type: boolean
TAGS:
    key: tags
    type: array
```

我们支持 `number`, (中文(简体) ), `boolean` 财务报告和审定财务报表 `array` 类型. 对于 `array` 类型,环境可变值应为逗号分隔字符串: `TAGS="foo,bar,fizz,buzz"` 将被投给 `['foo', 'bar', 'fizz', 'buzz']`。 。 。 .

### CONF FILES 覆盖

如果你有一堆变化 取决于环境 你运行你的应用, 定义其中的数十个地图可能很麻烦 `env_mapping.yaml` 文档.

此模块赋予您根据 `CONF_FILES` 环境可变值。 文件在 `CONF_FILES` 以同样的顺序装入, 这样 `CONF_FILES=google,extra`,它会装入 `/conf/google.yaml`,则 `/conf/extra.yaml`。 。 。 . 文件路径既可以是相对的(与CONF DIR Direct),也可以是绝对的.

假设我们有这些配置文件:

```yaml
# /conf/base.yaml
service: awesome
host: base.config.io
port: 8080
```

```yaml
# /conf/prod.yaml
host: prod.config.io
port: 8081
```

```yaml
# /conf/aws.yaml
host: prod.aws.config.io
```

```yaml
# /conf/google.yaml
host: prod.google.config.io
```

```yaml
# /conf/extra.yaml
port: 8082
```

和以下代码:

```javascript
// test.js
const config = require('@ekino/config')
console.log(config.get('service'))
console.log(config.get('host'))
console.log(config.get('port'))
```

如果我们运行这个剧本,我们将有:

```sh
node test.js
> awesome         # from base.yaml
> base.config.io  # from base.yaml
> 8080            # from base.yaml

CONF_FILES=prod node test.js
> awesome         # from base.yaml
> prod.config.io  # from prod.yaml
> 8081            # from prod.yaml

CONF_FILES=prod,aws node test.js
> awesome             # from base.yaml
> prod.aws.config.io  # from aws.yaml
> 8081                # from prod.yaml

CONF_FILES=prod,google node test.js
> awesome                # from base.yaml
> prod.google.config.io  # from google.yaml
> 8081                   # from prod.yaml

CONF_FILES=prod,google,extra node test.js
> awesome                # from base.yaml
> prod.google.config.io  # from google.yaml
> 8082                   # from extra.yaml
```

:警告: `env_mapping.yaml` 将永远优先于文件覆盖.

### 继承模式

```
base.yaml <— [<CONF_FILES>.yaml] <— [env_mapping.yaml]
```

_所有文件被包围 `[]` 是可选的._

1.  装入配置从 `<CONF_DIR>/base.yaml`
2.  若为 `CONF_FILES` 定义,如果每个对应文件存在,则加载
3.  若为 `<CONF_DIR>/env_mapping.yaml` 已存在, 并且一些环境变量匹配, 覆盖这些值

## 常见问题

### @ekino/config 是什么？

由yaml提供动力的轻量级配置模块

### 如何安装 @ekino/config？

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

### @ekino/config 支持 TypeScript 吗？

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

### @ekino/config 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ekino/config 可以商用吗？

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

### @ekino/config 的下载量有多少？

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

### @ekino/config 还在维护吗？

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