# @asyncapi/bundler 中文文档 规范地址：https://npmcn.com/package/%40asyncapi/bundler/ 版本：1\.1\.1 npm 元数据更新时间：2026-11-02T08:30:14.194Z 中文译文更新时间：2026-11-07T01:37:16.096Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40asyncapi/bundler 原文对照：https://npmcn.com/package/%40asyncapi/bundler/?lang=original 项目主页：https://github.com/asyncapi/cli/tree/master/packages/bundler#readme 源码仓库：https://github.com/asyncapi/cli ## 关键信息（来自 npm 元数据） - 包体积（解压后）：67.4 kB，18 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - Node.js 要求：\>=24 - 运行依赖：5 个 - 首次发布：2022-02-07T08:20:40.538Z - 最新版本发布：2026-11-02T08:30:13.886Z - 近 30 天下载量：579612（2026-10-07 至 2026-11-05，npm 官方下载统计） - 已发布版本数：39（近 12 个月 6 个） ## 中文简介 从单个 AsyncAPI 文档引用到单个文件 . ## 安装 ```sh npm install @asyncapi/bundler ``` 也可以使用：`pnpm add @asyncapi/bundler`、`yarn add @asyncapi/bundler`、`bun add @asyncapi/bundler` ## README [![AsyncAPI Bundler](https://npmcn.com/package/%40asyncapi/bundler/assets/logo.png)](https://www.asyncapi.com/) [![Github license](https://img.shields.io/github/license/asyncapi/cli)](https://github.com/asyncapi/cli/blob/master/packages/bundler/LICENSE) [![PR testing - if Node project](https://github.com/asyncapi/cli/actions/workflows/if-nodejs-pr-testing.yml/badge.svg)](https://github.com/asyncapi/cli/actions/workflows/if-nodejs-pr-testing.yml) [![npm](https://img.shields.io/npm/dw/@asyncapi/bundler)](https://www.npmjs.com/package/@asyncapi/bundler) 此软件包是在 [AsyncAPI CPI 单列波](https://github.com/asyncapi/cli/tree/master/packages/bundler)。 。 。 . - [概览](https://npmcn.com/package/%40asyncapi/bundler/#readme-overview) - [安装](https://npmcn.com/package/%40asyncapi/bundler/#readme-installation) - [使用量](https://npmcn.com/package/%40asyncapi/bundler/#readme-usage) - [外部参考资料的参考](https://npmcn.com/package/%40asyncapi/bundler/#readme-dereference-of-the-external-references) - [选项 `baseDir`](https://npmcn.com/package/%40asyncapi/bundler/#readme-option-basedir) - [财产 `x-origin`](https://npmcn.com/package/%40asyncapi/bundler/#readme-property-x-origin) - [部件移动到 `components`](https://npmcn.com/package/%40asyncapi/bundler/#readme-movement-of-components-to-components) - [代码示例](https://npmcn.com/package/%40asyncapi/bundler/#readme-code-examples) - [捆绑( 文件, \[选项\])](https://npmcn.com/package/%40asyncapi/bundler/#readme-bundlefiles-options) - [贡献者](https://npmcn.com/package/%40asyncapi/bundler/#readme-contributors) ## 概览 一个官方库,可以让你捆绑/调试或合并到您的 AsyncAPI 文档中. AsyncAPI 软件 Bundler可以帮助你,如果: 您的规格文件被分成不同的较小文件, 并且正在使用 JSON \`$ref' 属性来引用组件 ```yaml # asyncapi.yaml asyncapi: '2.4.0' info: title: Account Service version: 1.0.0 description: This service is in charge of processing user signups channels: user/signup: subscribe: message: $ref: './messages.yaml#/messages/UserSignedUp' # messages.yaml messages: UserSignedUp: payload: type: object properties: displayName: type: string description: Name of the user email: type: string format: email description: Email of the user # After combining asyncapi: 2.4.0 info: title: Account Service version: 1.0.0 description: This service is in charge of processing user signups channels: user/signedup: subscribe: message: payload: type: object properties: displayName: type: string description: Name of the user email: type: string format: email description: Email of the user ``` 您有不同的独立规格文件来定义更大的系统,请参见这里的例子 ```yaml # signup.yaml asyncapi: '2.4.0' info: title: Account Service version: 1.0.0 description: This service is in charge of processing user Signup channels: user/signedup: subscribe: message: payload: type: object properties: displayName: type: string email: type: string format: email # login.yaml asyncapi: '2.4.0' info: title: Account Service version: 1.0.0 description: This service is in charge of processing user signup channels: user/loggenin: subscribe: message: payload: type: object properties: displayName: type: string # After combining # asyncapi.yaml asyncapi: '2.4.0' info: title: Account Service version: 1.0.0 description: This service is in charge for processing user authentication channles: user/signedup: subscribe: message: payload: type: object properties: displayName: type: string email: type: string format: email user/loggedin: subscribe: message: payload: type: object properties: displayName: type: string ``` ## 安装 ``` npm install @asyncapi/bundler ``` ## 使用量 AsyncAPI 软件 Bundler 可以很容易地在您的 JavaScript 项目中用作节点.js 模块 : ```js 'use strict'; const { writeFileSync } = require('fs'); const bundle = require('@asyncapi/bundler'); async function main() { const document = await bundle(['social-media/comments-service/main.yaml'], { baseDir: 'example-data', xOrigin: true, }); if (document.yml()) { console.log(document.yml()); // the complete bundled AsyncAPI document writeFileSync('asyncapi.yaml', document.yml()); // the complete bundled AsyncAPI document } } main().catch(e => console.error(e)); ``` ### 外部参考资料的参考 `Bundler` 尽可能地调试所提供的 AsyncAPI 文档, 仅保留那些 MUSST 的内部引用 `Reference Object`s 根据 AsyncAPI 规格(因此,绝不应被忽略): - AsyncAPI 规格 v 2. 6.0 没有内部参考文献显示 `Reference Object`编号. - AsyncAPI 规格 v3. 0.0 内部参考文献 `Reference Object`编号: ``` /#\/channels\/.*\/servers/ /#\/operations\/.*\/channel/ /#\/operations\/.*\/messages/ /#\/operations\/.*\/reply\/channel/ /#\/operations\/.*\/reply\/messages/ /#\/components\/channels\/.*\/servers/ /#\/components\/operations\/.*\/channel/ /#\/components\/operations\/.*\/messages/ /#\/components\/operations\/.*\/reply\/channel/ /#\/components\/operations\/.*\/reply\/messages/ ``` ### 选项 `baseDir` 选项 `baseDir` 代表程序的主要工作目录“ root 目录” , 相对而言, 将解决 AsyncAPI 文档传递到 `Bundler`。 。 。 . 从 `Bundler` v0.5.0, 选项 `baseDir` 以改变逻辑的方式重新执行,以及 `Bundler` 仅接受 **路径** asyncAPI 文档,将随 `readFileSync()` 内部. 简言之,这个过程是这样的: - AsyncAPI 文档路径作为 `'main.yaml'` | `'./main.yaml'` | `'../main.yaml'` | `['./main.yaml']` | `['main.yaml', 'audio.yaml']`等 (中文(简体) ). - 路径/路径保证 `Array` 类型为 `Array.from()` 让他们可以活下来. - 程序的工作目录改为 `baseDir` 与 `process.chdir()`。 。 。 . - **只有这样** 是 AsyncAPI 文档的路径,从当前数组开始逐一读取,解析路径和 `$ref`s 相对 `baseDir`。 。 。 . 看看这个 `./example/bundle-cjs.cjs`,表明与 `baseDir` 财务报告和审定财务报表 `$ref`不同水平的巢穴. ### 财产 `x-origin` 财产 `x-origin` 用于源头追踪 `Bundler` 和组件命名 `Optimizer`。 。 。 . 来源于 [本评论](https://github.com/asyncapi/bundler/issues/97#issuecomment-1330501758) 在长达一年的讨论中: > $ref通常还带有一个表意来理解它是什么(例如"$ref: financial-system.yaml#/组件/schemas/ Bank AccountIdentifer"). 如果捆绑只是解决了这个 ref inline, $ref指针的示意图意义会丢失, 无法在后期步骤中恢复 。 优化器在移动到组件部分时需要为"银行会计识别器"发明一个人工组件名称. 因此,财产 `x-origin` 包含被忽略的历史值 `$ref`s,也用于 `Optimizer` 为它通过AsyncAPI文档移动的组件提供有意义的名称. 然而,如果用户不需要/不需要 `x-origin` asyncAPI 文档结构中的属性(值) `x-origin` 属性可能泄露AsyncAPI文档描述的系统结构的内部细节,) `{ xOrigin: false }` (或省略通过) `xOrigin` )改为: `Bundler` 在选项对象中. ### 部件移动到 `components` 所有 AsyncAPI 规格验证组件移动到 `components` asyncAPI 文档从 `Bundler` v0.5.0 由 [`Optimizer`](https://github.com/asyncapi/optimizer) v1.0.0+ (中文(简体) ). 要在 CI/ 编码中获取 AsyncAPI 文档,该文档将被删除 [尽最大可能](https://npmcn.com/package/%40asyncapi/bundler/#readme-dereference-of-the-external-references) 它的所有组件都移到 `components` 区域,原始 AsyncAPI 文档必须运行于链条 `Bundler -> Optimizer`。 。 。 . 若为 `Optimizer` 无法找到 `x-origin` 属性在优化提供的 AsyncAPI 文档时,将组件的现有名称用作倒置机制,但记住组件名称在此情况下可能缺乏语义意义. ### 代码示例 **类型脚本** ```ts import { writeFileSync } from 'fs'; import bundle from '@asyncapi/bundler'; async function main() { const document = await bundle(['social-media/comments-service/main.yaml'], { baseDir: 'example-data', xOrigin: true, }); if (document.yml()) { writeFileSync('asyncapi.yaml', document.yml()); } main().catch(e => console.error(e)); ``` **JavaScript CJS 模块系统** ```js 'use strict'; const { writeFileSync } = require('fs'); const bundle = require('@asyncapi/bundler'); async function main() { const document = await bundle(['social-media/comments-service/main.yaml'], { baseDir: 'example-data', xOrigin: true, }); if (document.yml()) { writeFileSync('asyncapi.yaml', document.yml()); } main().catch(e => console.error(e)); ``` **JavaScript 无害环境管理模块系统** ```js 'use strict'; import { writeFileSync } from 'fs'; import bundle from '@asyncapi/bundler'; async function main() { const document = await bundle(['social-media/comments-service/main.yaml'], { baseDir: 'example-data', xOrigin: true, }); if (document.yml()) { writeFileSync('asyncapi.yaml', document.yml()); } main().catch(e => console.error(e)); ``` ## 捆绑( 文件, \[选项\]) **仁爱**:全球职能 | 参数 | 类型 | 说明 | | --- | --- | --- | | 文件 | `string` | `Array.` | 应捆绑的 AsyncAPI 文档的一个或多个相对/绝对路径 . | | \[可选 | `Object` | | | \[选项.base\] | `string` | 一个相对/绝对的去向对象的路径,其属性将被保留. | | \[选项.baseDir\] | `string` | 一个相对/绝对的目录路径,相对于应该被捆绑的 AsyncAPI 文档路径,将会被解决. | | \[选项.xOrigin\] | `boolean` | 过 `true` 生成属性 `x-origin` 将包含历史价值 `$ref`编号. | ## 贡献者 感谢这些伟大的人[emoji 密钥](https://allcontributors.org/docs/en/emoji-key):
souvik
苏维克语
💻 🤔 🎨 👀 🚧 📖		Maciej Urbańczyk
马西杰·乌尔班奇克
🤔 👀		Mohd Toukir Khan
穆罕默德·图基尔·汗
🚇		MrYugs
杨先生
📖
Amanpreet Singh Bedi
阿芒普雷特·辛格·贝迪
📖		Alexey Vasilevich
阿列克谢·瓦西里耶维奇
📖		Viacheslav Turovskyi
维亚切斯拉夫·图罗夫斯基伊
💻 🚇 📖 🚧 👀 🤔		Lukasz Gornicki
卢卡斯·戈尔尼茨基
🚇 👀
Akshat Nema
阿克萨特·内马
💻		sambhavgupta0705
萨姆巴夫古普塔0705
💻
本项目遵循 [全部贡献者](https://github.com/all-contributors/all-contributors) 规格。 任何捐款都欢迎! ## 常见问题 ### @asyncapi/bundler 是什么？ 从单个 AsyncAPI 文档引用到单个文件 \. ### 如何安装 @asyncapi/bundler？ 在项目目录运行 npm install @asyncapi/bundler，或使用 pnpm add / yarn add / bun add。 ### @asyncapi/bundler 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @asyncapi/bundler 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @asyncapi/bundler 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @asyncapi/bundler 可以商用吗？ @asyncapi/bundler 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @asyncapi/bundler 的下载量有多少？ 根据 npm 官方下载统计，@asyncapi/bundler 在 2026/10/07 – 2026/11/05 这 30 天内被下载 579,612 次，日均约 19,320 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @asyncapi/bundler 还在维护吗？ 最新版本 1\.1\.1 发布于 2026/11/02（5 天前）；至今共发布 39 个版本，其中过去 12 个月发布了 6 个；首次发布于 2022/02/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。