# @clevercloud/reglage 中文文档

规范地址：https://npmcn.com/package/%40clevercloud/reglage/

版本：0\.0\.8
npm 元数据更新时间：2026-11-06T18:13:48.706Z
中文译文更新时间：2026-11-10T01:17:29.969Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：54.5 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：zod ^4
- 首次发布：2026-04-08T08:59:27.995Z
- 最新版本发布：2026-11-06T18:13:48.440Z
- 近 30 天下载量：12165（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

Schema驱动配置库:从多个命名源定义,验证并合并配置与Zod schemas,再以安全方式回读,并带有秘密掩码和Markdown doc生成.

## 安装

```sh
npm install @clevercloud/reglage
```

也可以使用：`pnpm add @clevercloud/reglage`、`yarn add @clevercloud/reglage`、`bun add @clevercloud/reglage`

## README

# @ cluvercloud/ reglage (英语)

Schema 驱动配置库 [佐德语Name](https://zod.dev/)。定义您的选项一次,然后从任何来源获得验证、类型安全配置.

## 使用量

```ts
import { createConfigBuilder } from '@clevercloud/reglage';
import { z } from 'zod';

const builder = createConfigBuilder({
  API_URL: {
    schema: z.url().default('https://api.example.com'),
    documentation: 'The API base URL',
  },
  PORT: {
    schema: z.number().default(8080),
    tags: ['server'],
    documentation: 'Port to listen on',
  },
  SECRET: {
    schema: z.string().min(1),
    secret: true,
    documentation: 'A required secret',
  },
});

builder.addSource('defaults', { PORT: '3000' });
builder.addSource('env', process.env);

const config = builder.buildConfig(); // throws InvalidConfigError on validation failure

config.get('API_URL'); // string
config.get('PORT'); // number
config.getAll('server'); // { PORT: number }
```

## API 密码

### `createConfigBuilder(schema)`

创建一个 `ConfigBuilder` 从一个计划记录。 每个关键地图到一个 `OptionDef`数字 :

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `schema` | `z.ZodType` | Zod schema用来验证并转换生值. |
| `secret` | `boolean` _(可选)_ | 将值标为敏感值. |
| `tags` | `string[]` _(可选)_ | 分类选项的任意标签 . |
| `documentation` | `string` | 人可读取的选项描述. |

### `ConfigBuilder`

#### `addSource(name, values)`

注册一个已命名的密钥/值源(例如:. `"env"`, (中文(简体) ), `"file"`) (中文(简体) ). 源被按顺序合并——后源为同一密钥而凌驾于前源. 计划中没有的密钥被默默地忽略了.

#### `buildConfig()`

将所有源合并,并验证每个值与计划相对应。 回返a `Config` 实例或扔出 `InvalidConfigError`。 。 。 .

#### `refine(key, fn)`

为给定的密钥添加跨字段验证规则。 回调接收了原Zod schema和所有已解析的配置值,必须返回一个Zod schema以验证字段对齐. 多重改进可以注册(即使是在同一键上). 在所有栏目被单独验证后运行.

```ts
// Make SECRET required when FEATURE_X is enabled
builder.refine('SECRET', (schema, resolved) => {
  if (resolved.FEATURE_X) return z.string().min(1);
  return schema;
});

// Restrict PORT in production
builder.refine('PORT', (schema, resolved) => {
  if (resolved.MODE === 'production') {
    return schema.refine((v) => v >= 1024, { message: 'Must be >= 1024 in production' });
  }
  return schema;
});
```

### `Config`

#### `get(key)`

返回单个密钥的解析值.

#### `getAll(tag?)`

返回所有已解析的值。 何时 `tag` 中仅包含标有该值的选项.

#### `getSource(key)`

返回为密钥提供中值的来源名称(例如:. `"env"`, (中文(简体) ), `"file"`),或 `"default"` 如果值来自 Zod 计划默认值.

#### `getSourceHistory(key)`

返回单个密钥的全部覆盖历史, 命令从最早( schema 默认值) 到最近( 赢取源) 。 每个条目都是 `SourceHistoryEntry`数字 :

```ts
interface SourceHistoryEntry {
  source: string;
  rawValue: unknown;
  resolvedValue?: unknown; // only set on the last (winning) entry
}
```

```ts
builder.addSource('file', { PORT: 3000 });
builder.addSource('env', { PORT: '8080' });
const config = builder.buildConfig();

config.getSourceHistory('PORT');
// [
//   { source: 'default', rawValue: 80 },
//   { source: 'file', rawValue: 3000 },
//   { source: 'env', rawValue: '8080', resolvedValue: 8080 }
// ]
```

#### `getAllSourceHistory()`

返回所有密钥的全部历史, 作为绘制每个密钥的对象 `SourceHistoryEntry[]`。 。 。 .

#### `toString(format?)`

返回所有配置值的可读字符串。 隐藏秘密值 `******`键按字母顺序排列.

-   **`"simple"`** (默认)——每键一行有中选来源:
    
    ```
    API_URL="https://api.example.com" (env)
    PORT=8080 (env)
    SECRET=****** (env)
    ```
    
-   **`"chain"`** – 每个键有完整源链的一行:
    
    ```
    API_URL="https://api.example.com" (default -> env)
    PORT=8080 (default -> file -> env)
    SECRET=****** (env)
    ```
    
-   **`"verbose"`** —— 多行输出, 显示每个源的原始值 `<-- active` 在中标条目上标记 :
    
    ```
    API_URL="https://api.example.com" (env)
      default -> "https://default.example.com"
      env     -> "https://api.example.com"  <-- active
    PORT=8080 (env)
      default -> 80
      file    -> 3000
      env     -> "8080"  <-- active
    SECRET=****** (env)
      default -> ******
      env     -> ******  <-- active
    ```
    

### `InvalidConfigError`

验证失败时抛出 。 显示 a `issues` 数组 `ConfigIssue` 对象 :

```ts
interface ConfigIssue {
  key: string;
  source: string | undefined;
  message: string;
}
```

## 常见问题

### @clevercloud/reglage 是什么？

Schema驱动配置库:从多个命名源定义,验证并合并配置与Zod schemas,再以安全方式回读,并带有秘密掩码和Markdown doc生成\.

### 如何安装 @clevercloud/reglage？

在项目目录运行 npm install @clevercloud/reglage，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @clevercloud/reglage 支持 TypeScript 吗？

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

### @clevercloud/reglage 支持 ESM 还是 CommonJS？

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

### @clevercloud/reglage 可以商用吗？

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

### @clevercloud/reglage 的下载量有多少？

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

### @clevercloud/reglage 还在维护吗？

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