@epiijs/config

关于

提供基础配置的定义、解析、校验、修正，和环境配置的动态加载能力，用于 @epiijs/server、@epiijs/client 等框架的应用配置。

从 0.x 升级到 1.x 是非兼容变更，请参考迁移说明升级。

设计原则

• 没有共识的约定都应该有配置项
• 尽可能零配置，每个配置项都提供默认行为
• 从 importConfig 加载得到的配置里，基础配置的字段都有有效值，环境配置可用 verifyConfig 自定义校验
• 每次加载配置必须指向一个具体应用，不能在多个应用间复用配置

典型项目结构

(root)
├─ src/
│  ├─ config/          # 配置源文件
│  │  ├─ config.default.ts
│  │  └─ config.prod.ts
│  └─ ...
├─ build/
│  ├─ config/          # 运行时从这里加载构建后的配置文件
│  └─ ...
├─ package.json
└─ tsconfig.json

配置定义

interface IAppConfig {
  appName: string;   // 应用名称，默认 unknown

  appRoot: string;   // 应用根目录，绝对路径

  appDirs: {         // 应用目录定义，通常不需要定制
    source: string;  // 来源目录，默认 src
    target: string;  // 目标目录，默认 build
    config: string;  // 配置目录，默认 config
  };

  appPort: number;   // 应用端口，默认 3000

  envName: string;   // 环境名称，默认 default

  envData: {         // 环境配置，根据环境名称动态加载得到，也可由调用方直接传入
    [key: string]: unknown;
  };
}

命名暗示：app* 字段是启动后不可变配置，env* 字段是启动后可变配置（将来可能会支持热重载）。

API

importConfig(config): Promise<IAppConfig>

功能：检查基础配置并加载环境配置。

import { importConfig } from '@epiijs/config';

const config = await importConfig({
  appRoot: '/path/to/app',
  envName: 'prod'
});

处理流程：

1. 基础配置（app*）校对：遇到无效值会兜底为默认值。appRoot 要求必填且是绝对路径且路径字符串安全，source 与 target 要求不相同。
2. 环境配置（env*）加载：从 appRoot/target/config 读取 config.default 与 config.${envName}，多个扩展名按 .mjs > .js 优先级。自定义 env 名字的配置覆盖 default 配置。文件缺失或加载失败视为没有提供配置，静默跳过。
3. 直接传入 envData 优先级最高，会跳过加载操作，但是输出提示性警告；任意 falsy 值视为未传入。

verifyConfig(config, validator)

功能：使用自定义校验器检查环境配置。

同步函数。把 envData 交给你的校验函数，校验通过后类型断言为指定类型。

import { importConfig, verifyConfig } from '@epiijs/config';

const config = await importConfig({ appRoot, envName: 'prod' });
const verified = verifyConfig(config, (envData) => {
  if (typeof envData.databaseUrl !== 'string') {
    throw new Error('envData.databaseUrl is required');
  }
  return { databaseUrl: envData.databaseUrl };
});

verified.envData.databaseUrl; // string

• 自定义校验的可用范围仅限 envData。
• 校验函数是普通函数，可按需选用 zod / JSON Schema 等协议的实现。

getDirNameByImportMeta(meta)

ESM 环境下替代 __dirname，接收 import.meta 返回当前文件所在目录。

import { getDirNameByImportMeta } from '@epiijs/config';
const appRoot = getDirNameByImportMeta(import.meta);

从 0.x 迁移

| 0.x | 1.x | |-----|-----| | verifyConfig(config) | importConfig(config) | | root | appRoot | | dirs.source / dirs.target | appDirs.source / appDirs.target | | （无） | appDirs.config 新增，默认 config | | dirs.client / dirs.server | 删除，不允许定制 | | port: { client, server } | appPort: number | | name | appName | | side | envData |

1.x 仍然导出 verifyConfig，与 0.x 同名不同义：它只负责校验 envData。