# @equinor/fusion-imports 中文文档

规范地址：https://npmcn.com/package/%40equinor/fusion-imports/

版本：2\.0\.8
npm 元数据更新时间：2026-11-12T09:54:33.797Z
中文译文更新时间：2026-11-13T20:17:39.873Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40equinor/fusion-imports
原文对照：https://npmcn.com/package/%40equinor/fusion-imports/?lang=original
源码仓库：https://github.com/equinor/fusion-framework

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

- 包体积（解压后）：223 kB，37 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2025-03-27T13:03:27.334Z
- 最新版本发布：2026-11-12T09:54:33.326Z
- 近 30 天下载量：11099（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 22 个）

## 中文简介

包导入文件和配置

## 安装

```sh
npm install @equinor/fusion-imports
```

也可以使用：`pnpm add @equinor/fusion-imports`、`yarn add @equinor/fusion-imports`、`bun add @equinor/fusion-imports`

## README

# @equinor/聚变-进口

用于导入和传输 TypeScript、 JavaScript 和 JSON 配置文件的工具 **节点.js 运行时间** 使用 [兴建](https://esbuild.github.io/)。 。 。 .

> \[大 此软件包与 **文件路径**,而不是 URL 。 它用于在运行时在Node.js CLI工具中加载配置脚本并构建管道.

## 安装

```bash
pnpm add @equinor/fusion-imports
```

## 何时使用

| 假设 | 函数 |
| --- | --- |
| 以基准名、 自动解析方式装入配置 `.ts` → `.js` → `.json` | `importConfig` |
| 在运行时间导入单个类型Script/JS模块( I) | `importScript` |
| 从磁盘读取并解析 JSON 文件 | `importJSON` |
| 查找一个碱名的第一个可访问配置文件 | `resolveConfigFile` |

## 快开始

```typescript
import { importConfig } from '@equinor/fusion-imports';

interface AppSettings {
  name: string;
  port: number;
}

// Resolves app.config.ts → app.config.js → app.config.json
const { config, path } = await importConfig<AppSettings>('app.config');
console.log(`Loaded ${path}:`, config);
```

## API 密码

### `importConfig<C>(basename, options?)`

通过碱名解析配置文件,按顺序检测扩展名( S)`.ts`, (中文(简体) ), `.mjs`, (中文(简体) ), `.js`, (中文(简体) ), `.json`). JSON文件直接解析;脚本文件被捆绑并被动态导入.

```typescript
import { importConfig } from '@equinor/fusion-imports';

interface MyConfig {
  name: string;
  bar: { foobar: number };
}

interface ScriptModule {
  generateConfig: (options: { env: string }) => MyConfig;
}

const { config } = await importConfig<MyConfig, ScriptModule>('my-config', {
  script: {
    resolve: (module) => module.generateConfig({ env: 'production' }),
  },
});
```

默认为模块 `default` 导出为配置值。 提供 `script.resolve` 以提取不同的导出或调用工厂函数.

#### 选项

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `baseDir` | `string` | 文件解析的基础目录( 默认 ): `process.cwd()`(中文(简体) ) |
| `extensions` | `string[]` | 探测扩展( 默认 ) : `['.ts', '.mjs', '.js', '.json']`(中文(简体) ) |
| `script.resolve` | `(module) => C` | 从导入模块提取配置值 |
| `script.esBuildOptions` | `ImportScriptOptions` | 转发到 `importScript` |

### `importScript<M>(entryPoint, options?)`

用 esbuilt(ESM,外接包)并动态地导入输出 。 自动包含两个内置的 esbuilt 插件 :

-   **`importMetaResolvePlugin`** - 决心 `import.meta.resolve()` 要求建立时的相对路径.
-   **`rawMarkdownPlugin`** ——支持 `?raw` 进口商品 `.md` 编号 : `.mdx` 文档.

```typescript
import { importScript } from '@equinor/fusion-imports';

interface Greeting { greet(name: string): string }
const mod = await importScript<Greeting>('./greet.ts');
console.log(mod.greet('World'));
```

#### 构建自定义

`ImportScriptOptions` 继承全部 `esbuild.BuildOptions` 除外 `entryPoints`, (中文(简体) ), `bundle`,以及 `format`。您可以通过自定义插件,定义化名,或者更改输出目录 :

```typescript
import { importScript } from '@equinor/fusion-imports';
import alias from 'esbuild-plugin-alias';

const mod = await importScript('./entry.ts', {
  plugins: [alias({ '@app': './src' })],
  outfile: '/tmp/bundle.js',
});
```

### `importJSON<T>(filePath, encoding?)`

从磁盘读取一个 JSON 文件并返回解析的内容。 随原出错投出为 `cause` 如果文件无法读取或包含无效的JSON.

```typescript
import { importJSON } from '@equinor/fusion-imports';

interface Manifest { name: string; version: string }
const manifest = await importJSON<Manifest>('./package.json');
```

### `resolveConfigFile(baseName, options?)`

返回第一个可访问配置文件的绝对路径,与给定的基准名和扩展名列表相匹配。 需要路径而不导入文件时有用 .

```typescript
import { resolveConfigFile } from '@equinor/fusion-imports';

const configPath = await resolveConfigFile('app.config', {
  baseDir: '/project',
  extensions: ['.ts', '.json'],
});
```

### 插件

#### `rawMarkdownPlugin(options?)`

拦截的 Esbuild 插件 `?raw` 用于标记下的文件和返回的导入 作为默认导出字符串的内容。 自动包含 `importScript`。 。 。 .

```typescript
// In a file bundled by importScript:
import readme from '../../README.md?raw';
console.log(readme); // raw markdown string
```

#### `createImportMetaResolvePlugin()`

替换的 Esbuild 插件 `import.meta.resolve('./relative')` 电话 已解决 `file://` 构建时的 URL 。 自动包含 `importScript`。 。 。 .

### 处理错误

软件包为文件系统故障提供了两个错误类别:

| 错误 | 掷出时 |
| --- | --- |
| `FileNotFoundError` | 文件不存在( E)`ENOENT`(中文(简体) ) |
| `FileNotAccessibleError` | 文件已存在但无法读取( I)`EACCES`, (中文(简体) ), `EISDIR`(中文(简体) ) |

两者均延长 `Error` 并附加原节点.js错误为 `cause`数字 :

```typescript
import { importConfig, FileNotFoundError } from '@equinor/fusion-imports';

try {
  await importConfig('missing');
} catch (error) {
  if (error instanceof FileNotFoundError) {
    console.error('Config not found:', error.message);
  }
}
```

## 常见问题

### @equinor/fusion-imports 是什么？

包导入文件和配置

### 如何安装 @equinor/fusion-imports？

在项目目录运行 npm install @equinor/fusion-imports，或使用 pnpm add / yarn add / bun add。

### @equinor/fusion-imports 支持 TypeScript 吗？

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

### @equinor/fusion-imports 支持 ESM 还是 CommonJS？

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

### @equinor/fusion-imports 可以商用吗？

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

### @equinor/fusion-imports 的下载量有多少？

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

### @equinor/fusion-imports 还在维护吗？

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