@kinngyo/load-config-file

动态加载配置文件，支持 TypeScript、JavaScript、ESM 和 CommonJS 配置格式。

说明：本包只负责加载配置文件本身，不会打包或转换配置文件中引用的第三方依赖。

安装

npm i @kinngyo/load-config-file --save-dev

yarn add @kinngyo/load-config-file -D

快速使用

创建配置文件：

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

加载配置：

import { loadConfigFile } from '@kinngyo/load-config-file'

const config = await loadConfigFile('config')

console.log(config)
// { port: 3000 }

路径用法

按名称查找，自动匹配扩展名：

const config = await loadConfigFile('config')

传入绝对路径：

const config = await loadConfigFile('/path/to/config.ts')

传入相对路径，相对于 root 解析：

const config = await loadConfigFile('./configs/app.config.js', process.cwd())

API

loadConfigFile

function loadConfigFile<T = any>(name: string, root?: string): Promise<T | null>

参数：

• name：配置文件名或路径。传入普通名称时不需要写扩展名。
• root：搜索根目录，默认值为 process.cwd()。

返回值：

• 找到并加载成功时，返回配置对象。
• 找不到文件或加载失败时，返回 null。

支持格式

支持以下扩展名：

.ts
.mts
.cts
.js
.mjs
.cjs

按名称查找时，优先级如下：

.ts -> .mts -> .cts -> .js -> .mjs -> .cjs

模块类型判断

明确模块格式优先：

• .mts / .mjs：按 ESM 加载。
• .cts / .cjs：按 CommonJS 加载。

.ts 和 .js 会参考项目 package.json 的 type 字段：

• type: "module"：优先按 ESM 加载。
• 其他情况：优先按 CommonJS 加载。

加载策略

整体流程：

loadConfigFile(name, root)
-> readConfigFile(name, root)
   -> 如果 name 是绝对路径：直接检查该文件
   -> 如果 name 是 ./ 或 ../ 相对路径：基于 root 解析后检查
   -> 如果 name 是普通名称：按扩展名优先级查找
-> 根据扩展名和 package.json type 判断优先模块格式
-> 按优先模块格式加载
   -> ESM：SWC 转译为 ESM -> 写入临时 .mjs -> import()
   -> CJS：SWC 转译为 CommonJS -> 写入临时 .cjs -> require()
-> 加载成功后返回配置对象
-> 加载失败时按降级规则尝试另一种模块格式
-> 清理临时文件

不同文件类型的主路径和降级路径：

| 文件类型 | 优先判断来源 | 主路径 | 降级路径 | | -------- | ----------------------------- | ---------------------------------- | -------------------------------- | | .ts | package.json 的 type 字段 | 按项目类型转译为 ESM 或 CJS 后加载 | 主路径失败后切换到另一种模块格式 | | .mts | 扩展名固定为 ESM | SWC 转译为 ESM -> import() | SWC 转译为 CJS -> require() | | .cts | 扩展名固定为 CJS | SWC 转译为 CJS -> require() | SWC 转译为 ESM -> import() | | .js | package.json 的 type 字段 | 按项目类型转译为 ESM 或 CJS 后加载 | 主路径失败后切换到另一种模块格式 | | .mjs | 扩展名固定为 ESM | SWC 转译为 ESM -> import() | 不降级为 CJS | | .cjs | 扩展名固定为 CJS | SWC 转译为 CJS -> require() | SWC 转译为 ESM -> import() |

降级规则：

• 优先按 ESM 加载时，先执行 import()；失败后尝试转为 CommonJS 并用 require() 加载。
• 优先按 CommonJS 加载时，先执行 require()；失败后尝试转为 ESM 并用 import() 加载。
• .mjs 是纯 ESM 文件，import() 失败后不会再尝试 require()。
• 两条路径都失败时，返回 null。

临时文件规则：

• ESM 路径会生成临时 .mjs 文件。
• CommonJS 路径会生成临时 .cjs 文件。
• 临时文件生成在配置文件同目录。
• 加载结束后会自动删除临时文件。

配置示例

ESM：

// config.ts
export default {
    name: 'app',
    port: 3000,
}

CommonJS：

// config.cjs
module.exports = {
    name: 'app',
    port: 3000,
}

注意事项

• TypeScript 只做转译，不做类型检查。
• 配置文件里的第三方依赖不会被打包。
• 加载过程中会在配置文件同目录生成临时 .mjs 或 .cjs 文件，并在加载完成后删除。
• 建议配置文件使用 export default 或 module.exports 导出配置对象。