confmix

一个通用的配置文件解析库，支持多种格式（JS、CJS、MJS、TS、CTS、MTS、JSON、YAML），并提供灵活的 TypeScript 转译方式。

安装

npm install confmix
# 或
pnpm add confmix
# 或
yarn add confmix

可选依赖

根据你选择的 TypeScript 解析方式，需要额外安装对应的依赖：

| 解析方式 | 额外依赖 | | ----------------- | ------------ | | ts-node（默认） | ts-node | | swc | @swc/core | | typescript | 无（已内置） |

# 使用 ts-node 模式（默认）
npm install ts-node

# 使用 swc 模式（更快）
npm install @swc/core

快速开始

import { parseConfig } from 'confmix'

const result = await parseConfig('./config.json')
console.log(result.config) // 配置内容
console.log(result.filepath) // 文件绝对路径
console.log(result.format) // 文件格式，如 'json'

API

parseConfig<T>(filepath, options?)

异步解析配置文件，返回 ParseResult<T>。

参数：

| 参数 | 类型 | 必填 | 说明 | | ---------- | ---------------- | ---- | -------------------------------------- | | filepath | string | ✅ | 配置文件路径（支持相对路径和绝对路径） | | options | TsParseOptions | ❌ | 解析选项，仅对 TS 文件生效 |

返回值： Promise<ParseResult<T>>

interface ParseResult<T = unknown> {
    config: T // 解析后的配置对象
    filepath: string // 文件的绝对路径
    format: string // 文件格式扩展名（不含点，如 'ts'、'json'）
}

TsParseOptions

TypeScript 文件的解析选项：

type TsParseOptions = {
    parseType?: 'ts-node' | 'swc' | 'typescript' // 默认: 'ts-node'
    disableInterpret?: boolean // 默认: false
}

| 选项 | 说明 | | ------------------ | ---------------------------------------------------------- | | parseType | 指定 TS 文件的转译方式，见下方详细说明 | | disableInterpret | 仅在 ts-node 模式下有效，禁用 rechoir 自动注册模块加载器 |

支持的文件格式

| 扩展名 | 格式 | 说明 | | ---------------- | -------------- | ------------------- | | .json | JSON | 标准 JSON 配置文件 | | .js | JavaScript | 自动识别 CJS / ESM | | .cjs | CommonJS | 强制 CommonJS 模块 | | .mjs | ESM | 强制 ES Module | | .ts | TypeScript | CommonJS 风格 TS | | .cts | TypeScript CJS | 强制 CommonJS 的 TS | | .mts | TypeScript ESM | 强制 ESM 的 TS | | .yaml / .yml | YAML | YAML 配置文件 |

TypeScript 解析模式详解

模式一：ts-node（默认）

使用 ts-node + rechoir 自动注册模块加载器来执行 TS 文件。

适用场景： 项目中已安装 ts-node，且需要完整的 TypeScript 类型检查支持。

前提条件： 需要在项目中安装 ts-node。

import { parseConfig } from 'confmix'

const result = await parseConfig('./config.ts')
// 等同于
const result = await parseConfig('./config.ts', { parseType: 'ts-node' })

⚠️ 注意：ts-node 模式依赖 rechoir 自动注册，如果环境中没有安装 ts-node，会抛出错误。

在 ESM 项目中使用 ts-node 模式

如果你的项目 package.json 中设置了 "type": "module"，ts-node 默认不支持 ESM，需要额外配置：

第一步：在 tsconfig.json 中启用 ESM 支持

{
    "compilerOptions": {
        "module": "ESNext",
        "moduleResolution": "Node16",
        "target": "ES2020",
        "esModuleInterop": true
    },
    "ts-node": {
        "esm": true
    }
}

第二步：通过 NODE_OPTIONS 环境变量启动程序

# Linux / macOS
NODE_OPTIONS="--loader ts-node/esm" node your-script.js

# Windows (PowerShell)
$env:NODE_OPTIONS="--loader ts-node/esm"; node your-script.js

# 或者直接使用 ts-node-esm 命令
npx ts-node-esm your-script.ts

💡 推荐：如果你的项目是 ESM 模式，建议直接使用 parseType: 'swc' 或 parseType: 'typescript' 模式，它们天然支持 ESM，无需额外配置。

模式二：swc（推荐，速度最快）

使用 @swc/core 将 TS 代码转译为 JS 后执行，无需 ts-node。

适用场景： 追求更快的解析速度，或不想依赖 ts-node 的场景。

前提条件： 需要安装 @swc/core。

import { parseConfig } from 'confmix'

const result = await parseConfig('./config.ts', { parseType: 'swc' })
console.log(result.config)

# 安装依赖
npm install @swc/core

模式三：typescript（内置，无额外依赖）

使用内置的 typescript 编译器将 TS 代码转译为 JS 后执行。

适用场景： 不想安装额外依赖，直接使用 confmix 内置的 TypeScript 编译器。

import { parseConfig } from 'confmix'

const result = await parseConfig('./config.ts', { parseType: 'typescript' })
console.log(result.config)

使用示例

解析 JSON 配置

// config.json
// { "host": "localhost", "port": 3000 }

import { parseConfig } from 'confmix'

const { config } = await parseConfig('./config.json')
console.log(config.host) // 'localhost'
console.log(config.port) // 3000

解析 YAML 配置

# config.yaml
app:
    name: 'My Application'
    version: '1.0.0'
    debug: true

import { parseConfig } from 'confmix'

const { config } = await parseConfig('./config.yaml')
console.log(config.app.name) // 'My Application'

解析 JS 配置（CommonJS）

// config.js
module.exports = {
    host: 'localhost',
    port: 3000
}

import { parseConfig } from 'confmix'

const { config } = await parseConfig('./config.js')
console.log(config.host) // 'localhost'

解析 JS 配置（ESM）

// config.mjs
export default {
    host: 'localhost',
    port: 3000
}

import { parseConfig } from 'confmix'

const { config } = await parseConfig('./config.mjs')
console.log(config.host) // 'localhost'

解析 TypeScript 配置（带类型）

// config.ts
export default {
    host: 'localhost',
    port: 3000,
    debug: true
}

import { parseConfig } from 'confmix'

interface AppConfig {
    host: string
    port: number
    debug: boolean
}

// 使用泛型获得类型提示
const { config } = await parseConfig<AppConfig>('./config.ts', {
    parseType: 'swc' // 或 'typescript'，无需安装 ts-node
})

console.log(config.host) // string 类型
console.log(config.port) // number 类型

解析 TypeScript CJS / ESM 配置

// config.cts（CommonJS TypeScript）
export default {
    name: 'my-app'
}

// config.mts（ESM TypeScript）
export default {
    name: 'my-app'
}

import { parseConfig } from 'confmix'

// 解析 .cts 文件
const result1 = await parseConfig('./config.cts', { parseType: 'swc' })

// 解析 .mts 文件
const result2 = await parseConfig('./config.mts', { parseType: 'swc' })

CommonJS 使用方式

const { parseConfig } = require('confmix')

async function main() {
    const { config } = await parseConfig('./config.json')
    console.log(config)
}

main()

错误处理

import { parseConfig } from 'confmix'

try {
    const result = await parseConfig('./config.ts', { parseType: 'swc' })
    console.log(result.config)
} catch (error) {
    // 文件不存在
    // Error: 配置文件未发现: /absolute/path/to/config.ts

    // 不支持的文件格式
    // Error: 不支持加载此配置文件的类型: xxx

    // TypeScript 编译错误
    // Error: TypeScript/SWC Error in config.ts: ...

    console.error(error.message)
}

各模式对比

| 特性 | ts-node | swc | typescript | | ---------- | ------------ | ------------ | ------------ | | 额外依赖 | ts-node | @swc/core | 无 | | 转译速度 | 慢 | ⚡ 最快 | 中等 | | 类型检查 | ✅ 完整 | ❌ 仅转译 | ❌ 仅转译 | | 无额外安装 | ❌ | ❌ | ✅ | | 推荐场景 | 需要类型检查 | 生产/CI 环境 | 轻量场景 |

类型导出

import type { ParseResult, TsParseOptions, ConfigLoader, DynamicImport } from 'confmix'

License

ISC