# @endo/bundle-source 中文文档

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

版本：4\.3\.2
npm 元数据更新时间：2026-06-12T04:47:41.067Z
中文译文更新时间：2026-11-13T16:55:08.404Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：101 kB，39 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：8 个
- 首次发布：2022-01-23T00:47:57.135Z
- 最新版本发布：2026-06-12T04:47:40.843Z
- 近 30 天下载量：22559（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：55（近 12 个月 4 个）

## 中文简介

从 ES 模块创建源捆

## 安装

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

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

## README

# 套装来源

此软件包从 ES 模块创建源包, 兼容 Endo 应用、Agoric合同和SwingSet wats.

将输入到 `program.js` 从命令行中,使用 `bundle-source` 工具:

```console
> yarn bundle-source --cache-json bundles program.js program
```

在方案方面采取同样的行动:

```js
import 'ses';
import bundleSource from '@endo/bundle-source';
import url from 'url';

const sourceBundleURL = new URL('program.js', import.meta.url);
const sourceBundlePath = url.fileURLToPath(sourceBundleURL);
const sourceBundleP = bundleSource(sourceBundlePath);
```

...为了得到一个承诺 一个源捆, 在阅读后解决 命名源并将其捆绑成可加载的表单,如所示 编辑 `moduleFormat` 见下文.

产生的捆绑适合与 `@endo/import-bundle`。 。 。 . 默认格式为捆绑为"endoZipBase64".

## 条件

介绍的节点.js [条件](https://nodejs.org/api/packages.html#conditional-exports)。 。 。 . 这个 `--condition`编号 :`-C` 选项相应影响 `bundle-source` 模块 决议.

“浏览器”条件还意味着选择 `browser` 替换条目 `main` 内 `package.json`,如果不是被明确的 `exports`。 。 。 .

“开发”条件还意味着捆绑可以导入 `devDependencies` 从包含输入模块的包中取出.

## 注释 Elision

这个 `--elide-comments`编号 :`-e` 选项,带有默认格式“endoZipBase64”或 通过“endoScript”来明确格式 `--format`编号 :`-f` 导致捆绑者空出 注释的内部,但不影响行或行号位置 剩余源代码. 这可以减少捆绑的大小,而不会对调试经验造成伤害 其他转变.

注释删除保留 `/*! slashasterbang /` 评论和联合来文文件评论 与 `@preserve`, (中文(简体) ), `@copyright`, (中文(简体) ), `@license` prasma 或 Internet 浏览器 `@cc_on` 破烂.

评论删除并不完全删除评论. 开始或结束的语法仍然保留.

## 类型 :

带有此选项的脚本模块 `.ts`, (中文(简体) ), `.mts`,以及 `.cts` 扩展 不属于 a 的软件包 `node_modules` 目录自动 通过类型去除而转换为 JavaScript [`amaro`](https://github.com/nodejs/amaro),则TypeScript 解析器节点.js使用 用于类型剥离.

这将不对作为原件发布的软件包起作用 类型脚本源, 符合 `node --experimental-strip-types`。 。 。 . 对于 TypeScript 模块,此功能也不会正常 [运行时间影响语法](https://nodejs.org/api/typescript.html#typescript-features), (中文(简体) ), 例如 `enum`。 。 。 .

这也不支持导入 a `.ts` 使用相应的文件 虚构、生成的模块 `.js` 扩展名. 结合 [`--allowImportingTsExtensions`](https://www.typescriptlang.org/tsconfig/#allowImportingTsExtensions)。 。 。 .

## 原始地图

默认 `moduleFormat` “endo ZipBase64”的组合器可以生成 源地图,但不包含在捆绑中. 使用 `cacheSourceMaps` 选项,将源地图转换成每个用户每个主机 缓存.

这个 `@endo/import-bundle` 工具可以添加这些生成的引用 解开捆绑时提供合适的源地图 `computeSourceMapLocation` 权力,就像由 `@endo/import-bundle/source-map-node.js`。 。 。 .

```js
import 'ses';
import { importBundle } from '@endo/import-bundle';
import { computeSourceMapLocation } from '@endo/import-bundle/source-map-node.js';
await importBundle(
  bundle,
  { endowments: { console } },
  { computeSourceMapLocation },
);
```

使用 `@endo/cli` 找到您的缓存.

```console
> yarn add -D @endo/cli
> yarn endo where cache
```

使用 `XDG_CACHE_HOME` 覆盖默认位置的环境变量 一般的缓存. 缓存将进入 `endo/source-map` 财务报告和审定财务报表 `endo/source-map-track`。 。 。 . 前者是每个捆绑的SHA-512上键入的内容地址存储 模块文件. 后者是SHA-512上按键的地址存储器 模块源的限定路径,表示已知的最后捆绑散列. 捆绑者使用跟踪器确保缓存只包含一个源 映射每个物理模块. 收集源头地图的源头尚不够聪明 不存在.

## `moduleFormat` 解释

### 获取导出

最原始的 `moduleFormat` 是“快递”. 它生成一个完成值( 上次评价的表达式) 的脚本 是接受可选的函数 `sourceUrlPrefix`。 。 。 .

```js
cosnt { source } = await bundleSource('program.js', { format: 'getExport' });
const exports = eval(source)();
```

以“ GetExport” 格式的捆绑可以导入主机模块 逻辑范围通用JS `require` 函数. 使用硬化的 Java 脚本可以赋予 `Compartment`。 。 。 .

```js
const compartment = new Compartment({
  globals: { require },
  __options__: true, // until SES and XS implementations converge
});
const exports = compartment.evaluate(source)();
```

> \[尖叫声\] “ GetExport” 格式以前使用过 [滚动](https://rollupjs.org/) 并用 `@endo/compartment-mapper/functor.js` 从第四版开始 `@endo/bundle-source`。 。 。 . 见 [嵌入式评价](https://npmcn.com/package/%40endo/bundle-source/#readme-nestedevaluate) 下面是兼容性说明.

### 嵌入式评价

这在逻辑上与"GetExport"格式相似,只是代码 可能还取决于 `nestedEvaluate(src)` 要使用的函数 在与母函数相同的上下文中评价子模块.

这种格式的优点是有助于保存文件名 如果有任何堆积痕迹,则捆绑.

“ 取消评价” 捆绑的完成值是接受 页:1 `sourceUrlPrefix` 用于捆绑中的每个模块,这些模块将显示在堆栈中 跟踪并协助调试者找到匹配的源文件.

```js
cosnt { source } = await bundleSource('program.js', { format: 'nestedEvaluate' });
const compartment = new Compartment({
  globals: {
    require,
    nestedEvaluate: source => compartment.evaluate(source),
  },
  __options__: true, // until SES and XS implementations converge
});
const exports = compartment.evaluate(source)('bundled-sources/.../');
```

在无 `nextedEvaluate` 函数在词典范围内,捆绑将 使用该 `eval` 函数.

> \[尖叫声\] “取消评价”格式以前使用过 [滚动](https://rollupjs.org/) 并用 `@endo/compartment-mapper/functor.js` 从第四版开始 `@endo/bundle-source`。 。 。 . 他们的行为并不相同.
> 
> 1.  第3版使用与Node.js 18不同的heuristics来推断是否 模块采用共同JS格式或无害环境管理格式。 4版没有猜测, 但依赖 `"type": "module"` 指令在 `package.json` 以显示 (单位:千美元) `.js` 扩展意味着无害环境管理格式,或尊重明确的 `.cjs` 财务报告和审定财务报表 `.mjs` 扩展.
> 2.  支持版本 3 [现场直播 约束](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#imported_values_can_only_be_modified_by_the_exporter) 第4版没有.
> 3.  版本 3 可以导入任何通过行走父目录可以发现的软件包 直到依赖或依赖在 `node_modules` 目录. 第4版要求依赖包明确注明依赖性 内 `package.json`。 。 。 .
> 4.  第3版和第4版生成不同的文本. 对案文的任何处理,如果对案文的确切外形敏感,则 文本很脆弱,甚至可能在小版本和补丁版本之间断开.
> 5.  第4版使已经由"endoZipBase64"格式支持的旗帜 普遍适用于所有格式,包括 `dev`, (中文(简体) ), `elideComments`, (中文(简体) ), `noTransforms`,以及 `conditions`。 。 。 .

## 内地脚本模块格式

这个 `ses` shim使用"endoScript"格式生成其发行捆绑, 适合在网页中插入 `<script>` 标签. 对于此格式,请提取 `source` 从生成的 JSON 信封和位置 放在你嵌入网页的文件里,一个Agoric [埃瓦尔核心](https://docs.agoric.com/guides/coreeval/) 脚本,或评价 任何接受脚本的地方.

```js
const { source } = await bundleSource('program.js', { format: 'endoScript' });
const compartment = new Compartment();
compartment.evaluate(source);
```

与“出口”和“取消评估”不同 `dev` 选项到 `bundleSource` 实值 任何捆绑的进口商品 `devDependencies`。 。 。 . “ endoScript” 格式不支持导入带有 CommonJS 的主机模块 `require`。 。 。 .

### 内地ZipBase64

远藤 (zip, base64) 捆绑是一个具有属性的天体:

-   `moduleFormat` 是"endoZipBase64"。 .
-   `endoZipBase64` 是一个以 Base64 编码的zip 文件.
-   `endoZipBase64Sha512`如果存在的话,是SHA-512 `compartment-map.json` 文件在 `endoZipBase64` 存档 . 如果 `compartment-map.json` 包括每个单元的SHA-512,这是 足以作为捆绑的应用程序的散列,以检查其完整性 无论程序是否从 存档 .

要检查 JSON 文件的捆绑内容 :

```sh
jq -r .endoZipBase64 | base64 -d | xxd | less
```

要提取内容:

```sh
jq -r .endoZipBase64 | base64 -d > bundle.zip
unzip bundle.zip -d bundle
```

在拉链文件中 `compartment-map.json` 表达整个联系 捆绑的程序,始于其输入模块,并明确标记“退出” 模块(必须配置的主机模块).

车厢图然后标出所有车厢和每个车厢 区间,指定将在区间中评估的每个模块. 这些指示了模块物理文本归档中的路径. 这个 `parser` 说明如何 `importBundle` 或等同的相位图 公用事业将解释模块的物理文本.

为了避免训练大型依赖和缓慢的汇编步骤,模块 在一个捆绑中,目前是预编译的,所以您不是找到源文本,而是 将找到JSON记录 描述模块的束缚和行为, 包括与源码相类似但并不相同的代码.

捆绑可能有这些 `parser` 属性 :

-   "pre-mjs-json":预编无害环境管理
-   "前Cjs-json":被预编为"共同JS"
-   “json”:生JSON(导出相应值为 `default`(中文(简体) )
-   “文本”:UTF-8编码文本(导出相应的字符串为 `default`(中文(简体) )
-   “字节”:一个octets序列(导出相应的 Uint8Array 为 `default`(中文(简体) )

一个JSON `pre-mjs-json` 模块将具有对象的所有属性 生成方式 `StaticModuleRecord` 从 `@endo/static-module-record`不过 特别是:

-   `__syncModuleProgram__`: 由无害环境管理转换而来的编码 来源于一个区块可以评估和约束其他无害环境管理的程序 此外,还实行了某些审查-回避改革.

因此,为了提取源-类似程序进行视觉检查:

```
jq -r .__syncModuleProgram__ module.js > module.source.js
```

## 常见问题

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

从 ES 模块创建源捆

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

在项目目录运行 npm install @endo/bundle-source，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 bundle-source，可以用 npx bundle-source 直接运行。

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

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

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

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

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

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

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

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

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

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