# @endo/import-bundle 中文文档

规范地址：https://npmcn.com/package/%40endo/import-bundle/

版本：1\.7\.0
npm 元数据更新时间：2026-06-12T04:53:48.571Z
中文译文更新时间：2026-11-13T16:53:44.519Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40endo/import-bundle
原文对照：https://npmcn.com/package/%40endo/import-bundle/?lang=original
项目主页：https://github.com/endojs/endo/tree/master/packages/import-bundle
源码仓库：https://github.com/endojs/endo

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

- 包体积（解压后）：42.4 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=12
- 运行依赖：6 个
- 首次发布：2022-01-23T00:47:57.135Z
- 最新版本发布：2026-06-12T04:53:48.357Z
- 近 30 天下载量：24570（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：52（近 12 个月 3 个）

## 中文简介

由 @endo/ bundle- source 创建的装入模块

## 安装

```sh
npm install @endo/import-bundle
```

也可以使用：`pnpm add @endo/import-bundle`、`yarn add @endo/import-bundle`、`bun add @endo/import-bundle`

## README

# 导入捆绑

`importBundle` 是用来评价由 : `bundle-source`,把它们重新变成可调用功能:

```js
const bundle = await bundleSource('path/to/bundle.js');
// 'bundle' is JSON-serializable
const options = {}; // filePrefix, endowments, other compartment options
const namespace = await importBundle(bundle);
const { default, namedExport1, namedExport2 } = namespace;
```

必须在 SES 环境中运行 : 在导入前必须安装 SES `@endo/import-bundle`。 。 。 . 常规的方法是导入一个模块(例如:. `@endo/init`哪个 已经 `import 'ses'; lockdown();`。 。 。 .

捆绑将装入一个新的座舱,该座舱无法进入 平台全局类 `document` 或者说 `Fetch` 或者说 `require`。 。 。 . 捆绑被隔离到只能使用无能的JavaScript设施 以及你提供的一切捐赠.

每次打给 `importBundle` 创建新 `Compartment`。 。 。 . 在任何捆绑代码被冻结之前,新Combetment的全局被冻结 被评估,以强制执行 ocap规则.

## 模块格式

源可以被捆绑在各种"格式"中.

### 内地ZipBase64

默认, `bundleSource` 使用命名格式 `endoZipBase64`,其中 在 Zip 文件 和 base- 64 中捕获源模块和"组合图" 已编码. 区间地图描述了如何构建一组 [硬化 Java 脚本](https://hardenedjs.org/) 车厢和如何装入和连接 它们之间的源模块.

### 内语脚本

这个 `endoScript` 格式以 JavaScript 单一程序抓取源 以输入模块的名称空间对象完成.

### 获取导出

这个 `getExport` 格式以单一的普通JS风格字符串来捕捉源, 并用可调用功能包起来,提供 `exports` 财务报告和审定财务报表 `module.exports` 可附加出口的上下文.

### 嵌入式评价

更精细 `getExport` 名称 `nestedEvaluate`。 。 。 . 在此模式下,源树被转换为可评价字符串表, 每个原始模块各一个. 此表再作编码并像以前一样包裹. 评价过程使用单独的评价员调用每个单元, 提供一种机会,使 `sourceMap` 对每一个. 在随后调试信息和堆栈中保存相对文件名 痕迹.

要为这些相对文件名设置一个基准前缀,请提供 `filePrefix` 选项.

注意 `nestedEvaluate` 格式收到全球捐赠名称 `require`,尽管只有在源树导入其中之一时才会叫它 数字化 `bundle-source` "外"名表.

### 测试

这个 `test` 格式用于在本地对捆绑进行测试,并且是 故意不能连载或通过. 在测试中使用此格式以避免需要从源代码生成捆绑, 仅提供您需要的导出 `importBundle`。 。 。 .

```js
import { importBundle, bundleTestExports } from '@endo/import-bundle';

test('who tests the tests', async t => {
  const bundle = bundleTestExports({ a: 10 });
  const namespace = await importBundle(bundle);
  t.is(namespace.a, 10);
  t.is(Object.prototype.toString.call(ns), '[object Module]');
});
```

## 选项

`importBundle()` 需要选项包和可选的额外权限.

```js
const namespace = await importBundle(bundle, options, powers);
```

最常见的选择是 `filePrefix`,可以提供 `nestedEvaluate`\- 格式捆绑. 设置捆绑内顶级模块的源文件名, 如 用于调试信件( 如错误中显示的堆栈痕迹) . 其它模块将基于其 位于原始源树内.

另一个常见的选择是 `endowments`,其中提供了将 在评估来源中,任何地方都有. 默认情况下, 捆绑只能访问标准的 JavaScript 基础`Array`, (中文(简体) ), `Object`, (中文(简体) ), `Map`(见e/cn.4/sub.2/2002/l.48等). 它不会得到 `document`, (中文(简体) ), `window`, (中文(简体) ), `Request`, (中文(简体) ), `process`, (中文(简体) ), `require`,或甚至 `console` 除非你把它们当作捐赠品 让你完全掌控 装满的捆绑可以做什么.

这个 `bundle-source` 工具有少量模块名称标记为 "外出" (中文(简体) ). 这些模块不会被捆绑到源中(从文件系统中复制到其中) `bundleSource` 被调用). 相反,捆绑者给 `require()` 每个外部模块 是从原始来源图中的某处导入的. 这使得最终评估环境能够控制这些进口所得, 而不是原始源树.

为了支持这些“外部”进口,您需要提供 `require` 任何这种名字都能被尊崇的天赋. 此外 `nestedEvaluate` 格式总是需要 `require` 捐赠 (尽管只有在原始来源进口其中一种时才使用) "外"名".

为了调试目的,你也许应该提供 `console` 捐赠. 见 `makeConsole.js` 在SwingSet源树中寻找灵感.

其余部分 `options` 传递到 `Compartment` 建筑师, 它目前只接受 `transforms`。 。 。 . 更多信息,请参见 `compartment-shim` 在 SES 仓库中的文件 . 请注意: `transforms` 被定义为每个对象都有一组 `rewrite` 方法.

请注意: `sloppyGlobalsMode` 只能被表层接受 `evaluate` 方法,而不是表层构造器本身,因此不能提供给 `importBundle`。 。 。 . 用于 `sloppyGlobalsMode`,您可能想要创建一个模拟 直接(而不是冻结其全球).

## 原始地图

对于一个远藤(zi, Base64)捆绑, `bundleSource` 将添加源地图到 a 每个用户缓存,如果导入在同一主机上,它们就可以被调试. 为了使用这个设施,通过一个 `computeSourceMapLocation` 能力进入 `powers`。 。 。 .

```js
import 'ses';
import bundleSource from '@endo/bundle-source';
import { importBundle } from '@endo/import-bundle';
import { computeSourceMapLocation } from '@endo/import-bundle/source-map-node.js';

lockdown();
const bundle = await bundleSource('debugme.js');
await importBundle(
  bundle,
  { endowments: { console } },
  { computeSourceMapLocation },
);
```

使用 `node --inspect-brk` 财务报告和审定财务报表 `debugger` 发言.

## 常见问题

### @endo/import-bundle 是什么？

由 @endo/ bundle- source 创建的装入模块

### 如何安装 @endo/import-bundle？

在项目目录运行 npm install @endo/import-bundle，或使用 pnpm add / yarn add / bun add。

### @endo/import-bundle 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/endo\_\_import-bundle 是否存在。

### @endo/import-bundle 支持 ESM 还是 CommonJS？

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

### @endo/import-bundle 需要什么版本的 Node\.js？

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

### @endo/import-bundle 可以商用吗？

@endo/import-bundle 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @endo/import-bundle 的下载量有多少？

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

### @endo/import-bundle 还在维护吗？

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