# @evumi/berth-config 中文文档

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

版本：0\.1\.25
npm 元数据更新时间：2026-11-13T02:39:14.669Z
中文译文更新时间：2026-11-14T02:44:58.312Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：45 kB，15 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-10-26T09:54:59.010Z
- 最新版本发布：2026-11-13T02:39:14.431Z
- 近 30 天下载量：16993（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：91（近 12 个月 91 个）

## 中文简介

Berth 專案的客戶端 Config:被缓存后以背景长波刷新来读取.

## 安装

```sh
npm install @evumi/berth-config
```

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

## README

# @evumi/berth-config

读取 Berth 项目 Config 的客户端。第一次读取时拉一次整份配置，之后都从内存读；后台用一个长轮询保持最新。零运行时依赖，支持 Node ≥ 18、Bun、Deno 和不带 Node 内置模块的 edge 运行时。

> **不要放机密。** Config 对组织成员可读。密码、密钥放到服务变量里。

此 SDK 用于服务端（包括服务端组件、API 路由和 edge Worker）。`BERTH_CONFIG_TOKEN` 是服务端凭据，同时用于环境的 KV 和队列等接口，不能下发到浏览器。前端需要配置或 KV 数据时，由应用后端校验权限并仅返回所需字段。不要把 Token 复制到 `NEXT_PUBLIC_*`、`VITE_*`、打包器环境变量映射或客户端 props；不要在客户端组件里使用此 SDK。

## 用法

Berth 会给容器注入 `BERTH_CONFIG_URL` 和 `BERTH_CONFIG_TOKEN`，直接用默认导出：

```ts
import { config } from '@evumi/berth-config';

const enabled = await config.get<boolean>('newCheckout');
const all = await config.getAll();
const unsubscribe = config.subscribe((doc) => console.log('config changed', doc));
```

自己建客户端：

```ts
import { createClient } from '@evumi/berth-config';

const cfg = createClient({
  url: process.env.BERTH_CONFIG_URL,   // 默认读环境变量
  token: process.env.BERTH_CONFIG_TOKEN,
  fallback: './config.local.json',     // 本地开发或启动时连不上服务器时使用
  timeoutMs: 5000,
  onError: (err) => console.warn('config:', err.code, err.message), // 默认什么都不打
});
```

| 方法 | 说明 |
| --- | --- |
| `get<T>(key)` | 某个顶层字段，不存在时返回 `undefined` |
| `getAll<T>(keys?)` | 整份文档，或只取给出的字段 |
| `has(key)` | 字段是否存在 |
| `digest()` | 当前 ETag（不带引号）；用的是 fallback 时为 `""` |
| `version()` | 当前版本号；还没有配置或用的是 fallback 时为 `0` |
| `subscribe(cb)` | 配置变化时回调，返回取消函数 |
| `close()` | 停止长轮询并中断进行中的请求 |

返回值是副本，改了不影响缓存。

## 行为

-   第一次调用任意方法时拉取 `GET /v1/config`，并发调用共用这一次请求；失败了下次调用会重试。
-   之后后台只有一个长轮询（`?wait=55` + `If-None-Match`），变化时立即更新并通知订阅者。
-   出错时按指数退避重试（带抖动，最长 30 秒）；429 按 `Retry-After` 等待。
-   Node 里长轮询的连接和定时器都已 `unref`，不会让进程退出不了；脚本里也不需要手动 `close()`。
-   错误都是 `BerthConfigError`，带 `code`（`unauthorized`、`not_found`、`unavailable`、`rate_limited`、`timeout`、`network`、`missing_env`、`fallback` 等）和 `status`。令牌不会出现在错误或日志里。

## Next.js

```ts
// app/page.tsx（服务端组件）
import { config } from '@evumi/berth-config';

export default async function Page() {
  const banner = await config.get<string>('banner');
  return <main>{banner && <p>{banner}</p>}</main>;
}
```

Edge 运行时也能用，`fallback` 只能传对象（edge 没有文件系统）。

## Express

```ts
import express from 'express';
import { config } from '@evumi/berth-config';

const app = express();
app.get('/', async (_req, res) => {
  const { maxItems = 20 } = await config.getAll<{ maxItems?: number }>();
  res.json({ maxItems });
});
app.listen(3000);
```

## 本地开发

本地没有 `BERTH_CONFIG_URL` / `BERTH_CONFIG_TOKEN` 时读 `fallback`：

```ts
const cfg = createClient({ fallback: './config.local.json' });   // 文件（Node/Bun/Deno）
const cfg2 = createClient({ fallback: { newCheckout: true } });  // 或直接给对象
```

没有环境变量也没有 `fallback` 时，读取会抛 `missing_env`。

## 开发

```sh
pnpm install
pnpm test    # 先构建，再跑 vitest（含 ESM/CJS 子进程退出测试）
pnpm build   # dist/esm + dist/cjs
```

## 常见问题

### @evumi/berth-config 是什么？

Berth 專案的客戶端 Config:被缓存后以背景长波刷新来读取\.

### 如何安装 @evumi/berth-config？

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

### @evumi/berth-config 支持 TypeScript 吗？

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

### @evumi/berth-config 支持 ESM 还是 CommonJS？

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

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

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

### @evumi/berth-config 可以商用吗？

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

### @evumi/berth-config 的下载量有多少？

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

### @evumi/berth-config 还在维护吗？

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