# @cyclonedx/cyclonedx-esbuild 中文文档

规范地址：https://npmcn.com/package/%40cyclonedx/cyclonedx-esbuild/

版本：1\.4\.4
npm 元数据更新时间：2026-08-11T10:14:32.297Z
中文译文更新时间：2026-11-11T06:57:29.255Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：77.2 kB，19 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.18\.0
- 运行依赖：5 个
- peer 依赖：esbuild \>=0\.11\.15
- 首次发布：2025-11-12T17:46:52.156Z
- 最新版本发布：2026-08-11T10:14:31.900Z
- 近 30 天下载量：133038（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

由 Esbuilt 或 Bun 所建项目创建 CyproogleDX 软件软件单(SBOM).

## 安装

```sh
npm install @cyclonedx/cyclonedx-esbuild
```

也可以使用：`pnpm add @cyclonedx/cyclonedx-esbuild`、`yarn add @cyclonedx/cyclonedx-esbuild`、`bun add @cyclonedx/cyclonedx-esbuild`

## README

# 气旋DX SBOM 生成器 _兴建_ 财务报告和审定财务报表 _阿宝_

[![shield\_npm-version](https://img.shields.io/npm/v/%40cyclonedx%2fcyclonedx-esbuild/latest?label=npm&logo=npm&logoColor=white "npm")](https://www.npmjs.com/package/@cyclonedx/cyclonedx-esbuild) [![shield\_gh-workflow-test](https://img.shields.io/github/actions/workflow/status/CycloneDX/cyclonedx-esbuild/nodejs.yml?branch=main&logo=GitHub&logoColor=white "tests")](https://github.com/CycloneDX/cyclonedx-esbuild/actions/workflows/nodejs.yml?query=branch%3Amain) [![shield\_coverage](https://img.shields.io/codacy/coverage/4900a38bdc544b2283695447e9513ab5?logo=Codacy&logoColor=white "test coverage")](https://app.codacy.com/gh/CycloneDX/cyclonedx-esbuild/dashboard) [![shield\_ossf-best-practices](https://img.shields.io/cii/percentage/11463?label=OpenSSF%20best%20practices "OpenSSF best practices")](https://www.bestpractices.dev/projects/11463) [![shield\_license](https://img.shields.io/github/license/CycloneDX/cyclonedx-esbuild?logo=open%20source%20initiative&logoColor=white "license")](https://github.com/CycloneDX/cyclonedx-esbuild/blob/main/LICENSE)  
[![shield\_website](https://img.shields.io/badge/https://-cyclonedx.org-blue.svg "homepage")](https://cyclonedx.org/) [![shield\_slack](https://img.shields.io/badge/slack-join-blue?logo=Slack&logoColor=white "slack join")](https://cyclonedx.org/slack/invite) [![shield\_groups](https://img.shields.io/badge/discussion-groups.io-blue.svg "groups discussion")](https://groups.io/g/CycloneDX) [![shield\_twitter-follow](https://img.shields.io/badge/Twitter-follow-blue?logo=Twitter&logoColor=white "twitter follow")](https://twitter.com/CycloneDX_Spec)

* * *

创建 _[旋风DX](https://cyclonedx.org/)_ 软件 材料单(SBOM) _[兴建](https://esbuild.github.io/)_ 或者说 _[阿宝](https://bun.com/)_。 。 。 .

本套件提供:

-   (单位:千美元) **用于 _兴建_\- 兼容的捆绑机** - 与 _兴建_ 财务报告和审定财务报表 _阿宝_
-   (单位:千美元) **CLI 工具** 从相容的建筑生成SBOMS [元文件](https://esbuild.github.io/api/#metafile)

工具使用捆绑过程中产生的依赖关系信息创建目录 和依赖图(即为什么将一个组件纳入最后捆绑).  
只有实际包含在最后捆绑中的依赖性(在 [树摇](https://esbuild.github.io/api/#tree-shaking)页:1.

生成的 SBOM 文件如下 [正式规格和标准](https://github.com/CycloneDX/specification), (中文(简体) ), 并可能具有属性 [`cdx:esbuild` 命名空间分类学](https://cyclonedx.github.io/cyclonedx-property-taxonomy/cdx/esbuild.html) 财务报告和审定财务报表 [`cdx` 命名空间分类学](https://cyclonedx.github.io/cyclonedx-property-taxonomy/cdx.html)。 。 。 .

## 特征

-   🔌 **用于相容捆绑器的插件** (单位:千美元)_兴建_, (中文(简体) ), _阿宝_(中文(简体) )
-   🖥️ **CLI 工具** 从相容元文件生成 SBOMS
-   QQ 支持多个 **旋风DX光谱版本** (1.2、1.3、1.4、1.5、1.6、1.7)
-   从捆绑的项目中提取组件和依赖性
-   📝 **许可证证据的收集**
-   ✅ **验证** 生成 SBOMS 对抗气旋DX 计划
-   🔄 **可复制产出** 选项,用于一致的 SBOM 生成
-   与 _类型脚本_, (中文(简体) ), _角质_和其他现代框架

## 所需资源

下列运行时间之一:

-   _节点.js_ `>= 20.18`
-   _阿宝_ `>= 1.3.6`

某些特征需要可选(同级)依赖性——见 `package.json` 用于版本限制.

-   _兴建_ —— 使用有 esbuilt 的插件时需要
-   _页:1_, (中文(简体) ), _ajv 格式_ 打开 _ajv-formats-草案2019_ ——SBOM JSON结果验证所需

## 安装

使用您首选的软件包管理器并安装为 dev- dependency :

```shell
npm install --save-dev @cyclonedx/cyclonedx-esbuild
pnpm add --save-dev @cyclonedx/cyclonedx-esbuild
yarn add --dev @cyclonedx/cyclonedx-esbuild
bun add --dev @cyclonedx/cyclonedx-esbuild
```

## 使用量

### 插件使用( 构建和组件)

该插件与 **相容的捆绑机**。 。 。 .  
由于 Bun 提供了与 esbuild 兼容的插件 API,因此同一插件可以在两种环境中使用.

#### 插件选项配置( C)

| 名称 | 类型 | 默认 | 说明 |
| :-- | :-: | :-: | :-- |
| **`specVersion`** | `{string}`  
其中一个: `"1.2"`, (中文(简体) ), `"1.3"`, (中文(简体) ), `"1.4"`, (中文(简体) ), `"1.5"`, (中文(简体) ), `"1.6"`, (中文(简体) ), `"1.7"` | `"1.6"` | \[CycloneDX- spec\] 的哪个版本要使用.  
支持的值取决于安装的依赖性 [旋风DX-javascript-图书馆](https://github.com/CycloneDX/cyclonedx-javascript-library/)。 。 。 . |
| **输出文件** | `{string}` | `"bom.json"` | 输出文件路径 . |
| **组图文集** | `{boolean}` | `false` | 搜索组件中的许可证文件,并将其作为许可证证据.  
这个特征是实验性的. |
| **可复制** | `{boolean}` | `false` | 是否要多走一英里, 使输出可复制 .  
这需要更多的资源,并可能导致时间价值和随机价值的损失. |
| **mc 类型** | `{string}` | `"application"` | 设置主组件类型 .  
见 [有效数值列表](https://cyclonedx.org/docs/1.7/json/#metadata_component_type)。 。 。 . |
| **验证** | `{boolean | undefined}` | `undefined` | 输出前验证生成的 BOM .  
如果不符合要求,则取消验证. |
| **日志级别** | `{string | undefined}` | `undefined` | 控制插件的动词。 接受由 [兴起的 `logLevel`](https://esbuild.github.io/api/#log-level) 或 Bun 中的相应设置.  
如果没有设定,插件将继承 `logLevel` 从构建配置。 如果该值也是未定义的,它会回到 `"warning"`。 。 。 . |

#### 插件示例: 新建

```javascript
// build.js
const esbuild = require('esbuild');
const { cyclonedxEsbuildPlugin } = require('@cyclonedx/cyclonedx-esbuild');

/** @type {import('@cyclonedx/cyclonedx-esbuild').CycloneDxEsbuildPluginOptions} */
const cyclonedxEsbuildPluginOptions = {
  specVersion: '1.7',
  outputFile: 'bom.json'
}

esbuild.build({
  // ...
  plugins: [
    cyclonedxEsbuildPlugin(cyclonedxEsbuildPluginOptions),
  ]
});
```

参见实例: [与建设一体化](https://github.com/CycloneDX/cyclonedx-esbuild/tree/main/examples/plugin-esbuild)。 。 。 .

#### 插件示例: Bun

自兹 _阿宝_插件 API 简约基于 _兴建_'s, 此插件也可以用于 _阿宝_ 使用内置捆绑器(Bun v1.3.6+)的项目.

```typescript
// build.ts
import { cyclonedxEsbuildPlugin } from "@cyclonedx/cyclonedx-esbuild"

await Bun.build({
  // ...
  metafile: true, // required for `cyclonedxEsbuildPlugin` to work with Bun
  plugins: [
    cyclonedxEsbuildPlugin({
      outputFile: "bom.json",
      // ...
    }),
  ],
})

export {}
```

参见实例: [与 Bun 合并](https://github.com/CycloneDX/cyclonedx-esbuild/tree/main/examples/plugin-bun)。 。 。 .

### CLI 工具

用于生成 SBOMS 的命令行接口 [建立元文件](https://esbuild.github.io/api/#metafile)。 。 。 .

#### CLI 调用

调用 CLI 取决于所使用的安装方法 .  
以下是各种软件包管理器和设置的例子:

```shell
npm exec -- cyclonedx-esbuild --help
pnpm exec cyclonedx-esbuild --help
yarn exec cyclonedx-esbuild --help
```

#### CLI 帮助页面

```text
Usage: cyclonedx-esbuild [options] <metafile>

Create CycloneDX Software Bill of Materials (SBOM) from esbuild-compatible metafile.

Arguments:
  metafile                          Path to esbuild-compatible metafile

Options:
  --bwd, --build-working-dir <dir>  Working dir used in the build process.
                                    (default: current working dir)
  --gather-license-texts            Search for license files in components and include them as license evidence.
                                    This feature is experimental. 
                                    (default: false)
  --sv, --spec-version <version>    Which version of CycloneDX spec to use. 
                                    (choices: "1.2", "1.3", "1.4", "1.5", "1.6", "1.7", default: "1.6")
  --output-reproducible             Whether to go the extra mile and make the output reproducible.
                                    This requires more resources, and might result in loss of time- and random-based-values. 
                                    (env: BOM_REPRODUCIBLE)
  -o, --output-file <file>          Path to the output file.
                                    Set to "-" to write to STDOUT.
                                    (default: write to STDOUT)
  --validate                        Validate resulting BOM before outputting.
                                    Validation is skipped, if requirements not met.
  --no-validate                     Disable validation of resulting BOM.
  --mc-type <type>                  Type of the main component.
                                    (choices: "application", "firmware", "library", default: "application")
  -v, --verbose                     Increase the verbosity of messages.
                                    Use multiple times to increase the verbosity even more.
  -V, --version                     output the version number
  -h, --help                        display help for command
```

### 以角为单位使用

对于 _角质_ 使用 _兴建_ (Angular 17+),您可以从构建数据生成SBOMS.

```jsonc
// package.json
{
  "scripts": {
    "build:app": "ng build --stats-json",
    "build:sbom": "cyclonedx-esbuild --gather-license-texts --output-reproducible -o dist/bom.json dist/stats.json",
    "build": "npm run build:app && npm run build:sbom"
  }
}
```

例如: [与Angular20的融合](https://github.com/CycloneDX/cyclonedx-esbuild/tree/main/tests/_testbeds/angular20-npm)。 。 。 .

## 内部

这种工具利用 [旋风DX库](https://github.com/CycloneDX/cyclonedx-javascript-library/) 生成实际数据结构.

除了班级 `CycloneDxEsbuildPlugin` 和接口 `CycloneDxEsbuildPluginOptions`, (中文(简体) ),  
这个 _兴建_ 插件和此工具确实 **没有** 披露任何额外的 _公开_ API或类 - 所有代码都是为了内部的,在版本升级时可能会不经任何通知而更改.

但是,CLI是稳定的,你可以称之为程序上的:

```javascript
const { execFileSync } = require('child_process')
const { constants: { MAX_LENGTH: BUFFER_MAX_LENGTH } } = require('buffer')
const sbom = JSON.parse(execFileSync(process.execPath, [
    '../path/to/this/package/bin/cyclonedx-esbuild-cli.js',
    '--spec-version', '1.7',
    '--output-file', '-'
    // additional CLI args
], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'buffer', maxBuffer: BUFFER_MAX_LENGTH }))
```

## 发展和贡献

随意打开问题,错误报告或调取请求.  
见 [捐款](https://github.com/CycloneDX/cyclonedx-esbuild/blob/main/CONTRIBUTING.md) 详细文件.

## 许可证

根据Apache 2.0许可证的规定,允许修改和再分配.  
见 [自由主义](https://github.com/CycloneDX/cyclonedx-esbuild/blob/main/LICENSE) 完整许可证存档.

## 常见问题

### @cyclonedx/cyclonedx-esbuild 是什么？

由 Esbuilt 或 Bun 所建项目创建 CyproogleDX 软件软件单\(SBOM\)\.

### 如何安装 @cyclonedx/cyclonedx-esbuild？

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

### @cyclonedx/cyclonedx-esbuild 支持 TypeScript 吗？

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

### @cyclonedx/cyclonedx-esbuild 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @cyclonedx/cyclonedx-esbuild 需要什么版本的 Node\.js？

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

### @cyclonedx/cyclonedx-esbuild 可以商用吗？

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

### @cyclonedx/cyclonedx-esbuild 的下载量有多少？

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

### @cyclonedx/cyclonedx-esbuild 还在维护吗？

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