# @cyclonedx/cyclonedx-library 中文文档
规范地址：https://npmcn.com/package/%40cyclonedx/cyclonedx-library/
版本：10\.5\.0
npm 元数据更新时间：2026-11-09T12:25:12.366Z
中文译文更新时间：2026-11-11T06:56:28.484Z
软件包许可：Apache-2\.0
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40cyclonedx/cyclonedx-library
原文对照：https://npmcn.com/package/%40cyclonedx/cyclonedx-library/?lang=original
项目主页：https://github.com/CycloneDX/cyclonedx-javascript-library#readme
源码仓库：https://github.com/CycloneDX/cyclonedx-javascript-library
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：5.3 MB，610 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.18\.0
- 运行依赖：0 个
- peer 依赖：ajv ^8\.12\.0，libxmljs2 ^0\.35\|\|^0\.37，ajv-formats ^3\.0\.1，xmlbuilder2 ^3\.0\.2\|\|^4\.0\.0，packageurl-js \*，ajv-formats-draft2019 ^1\.6\.1，spdx-expression-parse \*
- 首次发布：2022-06-08T21:26:14.354Z
- 最新版本发布：2026-11-09T12:25:11.981Z
- 近 30 天下载量：3112600（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：123（近 12 个月 18 个）
## 中文简介
用于JavaScript(Node.js或Web Browser)的CyroundDX核心功能.
## 安装
```sh
npm install @cyclonedx/cyclonedx-library
```
也可以使用：`pnpm add @cyclonedx/cyclonedx-library`、`yarn add @cyclonedx/cyclonedx-library`、`bun add @cyclonedx/cyclonedx-library`
## README
# 旋风DX JavaScript 库
[](https://www.npmjs.com/package/%40cyclonedx/cyclonedx-library) [](https://cyclonedx-javascript-library.readthedocs.io/) [](https://github.com/CycloneDX/cyclonedx-javascript-library/actions/workflows/nodejs.yml?query=branch%3Amain) [](https://app.codacy.com/gh/CycloneDX/cyclonedx-javascript-library/dashboard) [](https://www.bestpractices.dev/projects/7883) [](https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/LICENSE)
[](https://cyclonedx.org/) [](https://cyclonedx.org/slack/invite) [](https://groups.io/g/CycloneDX) [](https://twitter.com/CycloneDX_Spec)
* * *
西非办事处 [旋风DX](https://cyclonedx.org/) 是一个完整的材料清单和系统透明度标准 提供软件、服务、硬件和AI组件的能见度,使高级供应链安全和网络风险降低成为可能.
此软件包提供了 _旋风DX_ 页:1 _Java 脚本_ (单位:千美元)_节点.js_ 或者说 _网页浏览器_, (中文(简体) ), 写入 _类型脚本_ 并编集为目标.
> \[注\]
> 这个软件包是一个软件库,不准备单独使用.
> 用于生成软件手册(SBOM)的工具和插件列表,请检查 [元包装](https://github.com/CycloneDX/cyclonedx-node-module?tab=readme-ov-file#readme)。 。 。 .
## 责任
- 提供一般目的 _Java 脚本_\- 实施 [_旋风DX_](https://cyclonedx.org/) 页:1 _节点.js_ 财务报告和审定财务报表 _网页浏览器_。 。 。 .
- 为所述执行提供打字,这样开发者和dev-tool就可以依赖.
- 提供数据模型与 _旋风DX_。 。 。 .
- 提供JSON和XML正常剂,即...
- 支持所有已运出的数据模型.
- 尊重任何注入 [_旋风DX_ 规格](https://github.com/CycloneDX/specification/#readme) 并据此生成有效的输出.
- 可配置以生成可再生产/决定性输出.
- 可以为JSON-和XML-序列化准备数据结构.
- 序列化 :
- 为所有目标环境提供通用的JSON序列器.
- 为所有目标环境提供 XML 序列器 .
- 支持在下游实施适合特定环境的自定义XML序列器
提供抽象的基础课,照顾到正常化和BomRef歧视.
这样做是因为没有通用的 XML 支持 _Java 脚本_。 。 。 .
- 根据 [_旋风DX_ 规格](https://github.com/CycloneDX/specification/#readme). (目前为 _节点.js_ 仅限)
## 能力
- 下列用例的用量:
- `AttachmentEncoding`
- `ComponentScope`
- `ComponentType`
- `ExternalReferenceType`
- `HashAlgorithm`
- `Vulnerability` 有关:
- `AffectStatus`
- `AnalysisJustification`
- `AnalysisResponse`
- `AnalysisState`
- `RatingMethod`
- `Severity`
- 下列使用案例的数据模型:
- `Attachment`
- `Bom`
- `BomLink`, (中文(简体) ), `BomLinkDocument`, (中文(简体) ), `BomLinkElement`
- `BomRef`, (中文(简体) ), `BomRefRepository`
- `Component`, (中文(简体) ), `ComponentRepository`, (中文(简体) ), `ComponentEvidence`
- `ExternalReference`, (中文(简体) ), `ExternalReferenceRepository`
- `Hash`, (中文(简体) ), `HashContent`, (中文(简体) ), `HashDictionary`
- `LicenseExpression`, (中文(简体) ), `NamedLicense`, (中文(简体) ), `SpdxLicense`, (中文(简体) ), `LicenseRepository`
- `Metadata`
- `OrganizationalContact`, (中文(简体) ), `OrganizationalContactRepository`
- `OrganizationalEntity`, (中文(简体) ), `OrganizationalEntityRepository`
- `Property`, (中文(简体) ), `PropertyRepository`
- `SWID`
- `Tool`, (中文(简体) ), `ToolRepository`, (中文(简体) ), `Tools`
- `Vulnerability` 有关:
- `Advisory`, (中文(简体) ), `AdvisoryRepository`
- `Affect`, (中文(简体) ), `AffectRepository`, (中文(简体) ), `AffectedSingleVersion`, (中文(简体) ), `AffectedVersionRange`, (中文(简体) ), `AffectedVersionRepository`
- `Analysis`
- `Credits`
- `Rating`, (中文(简体) ), `RatingRepository`
- `Reference`, (中文(简体) ), `ReferenceRepository`
- `Source`
- `Vulnerability`, (中文(简体) ), `VulnerabilityRepository`
- 下列用途的水电费:
- 生成有效的随机序列号 `Bom.serialNumber`
- 从文件中收集许可证证据(用于: _节点.js_ 仅限)
- 下列使用的工厂:
- 从任何许可描述字符串创建数据模型
- 具体针对 _节点.js_: 从类似Json的数据结构和衍生数据创建数据模型
- 用于下列用途的构建器:
- 具体针对 _节点.js_: 创建深层数据模型 `Tool` 或者说 `Component` 从类似Json软件包的数据结构
- 执行《公约》 [_旋风DX_ 规格](https://github.com/CycloneDX/specification/#readme) 用于下列版本:
- `1.7`
- `1.6`
- `1.5`
- `1.4`
- `1.3`
- `1.2`
- 将数据模型转换为 JSON 结构的常态化器
- 将数据模型转换为 XML 结构的常态器
- 转换的通用序列器 `Bom` 数据模型到 JSON 字符串
- 转换特定序列器 `Bom` xML 字符串的数据模型 :
- 具体针对 _网页浏览器_: 执行时使用特定浏览器的文档生成器和打印机.
- 具体针对 _节点.js_执行:利用 [可选依赖关系](https://npmcn.com/package/%40cyclonedx/cyclonedx-library/#readme-optional-dependencies) 说明如下:
- JSON 字符串和 XML 字符串的正式验证器( 目前用于 _节点.js_ 仅限)
要求数 [可选依赖关系](https://npmcn.com/package/%40cyclonedx/cyclonedx-library/#readme-optional-dependencies) 说明如下:
## 安装
该软件包和构建结果可供 _无_, (中文(简体) ), _小时_ 财务报告和审定财务报表 _线条_数字 :
```shell
npm i -S @cyclonedx/cyclonedx-library
pnpm add @cyclonedx/cyclonedx-library
yarn add @cyclonedx/cyclonedx-library
```
你可以从源头安装软件包, 将自动在安装的基础上建立:
```shell
npm i -S github:CycloneDX/cyclonedx-javascript-library
pnpm add github:CycloneDX/cyclonedx-javascript-library
yarn add @cyclonedx/cyclonedx-library@github:CycloneDX/cyclonedx-javascript-library # only with yarn-2
```
## 可选同伴依赖关系
一些特性需要可选的对等依赖性——见 `package.json` 用于版本细节.
- 串行到 XML 上 _节点.js_ 要求:
- [`xmlbuilder2`](https://www.npmjs.com/package/xmlbuilder2)
- JSON 的验证 _节点.js_ 要求所有:
- [`ajv`](https://www.npmjs.com/package/ajv)
- [`ajv-formats`](https://www.npmjs.com/package/ajv-formats)
- [`ajv-formats-draft2019`](https://www.npmjs.com/package/ajv-formats-draft2019)
- XML 上的验证 _节点.js_ 要求:
- [`libxmljs2`](https://www.npmjs.com/package/libxmljs2)
- 系统可能需要满足 [`node-gyp`](https://github.com/TooTallNate/node-gyp#installation),在某些情况下.
此外,我们还就相关的第三方标准提出了一些建议:
- [`packageurl-js`](https://www.npmjs.com/package/packageurl-js) 用于制作和解析软件包URL.
- [`spdx-expression-parse`](https://www.npmjs.com/package/spdx-expression-parse) 用于验证 SPDX 许可证表达式.
## 使用量
参见扩展 [实例](https://github.com/CycloneDX/cyclonedx-javascript-library/tree/main/examples/README.md)。 。 。 .
### 作为 _节点.js_ 软件包
```javascript
const CDX = require('@cyclonedx/cyclonedx-library')
const bom = new CDX.Models.Bom()
bom.metadata.component = new CDX.Models.Component(
CDX.Enums.ComponentType.Application,
'MyProject'
)
const componentA = new CDX.Models.Component(
CDX.Enums.ComponentType.Library,
'myComponentA',
)
bom.components.add(componentA)
bom.metadata.component.dependencies.add(componentA.bomRef)
```
确保最佳 **树起摇动** 何时 **捆绑**,只导入您实际需要的符号 [切入点](https://nodejs.org/api/packages.html#package-entry-points)。 您可以在 `exports` 软件包字段 `package.json`。 。 。 .
```javascript
const { Bom, Component } = require('@cyclonedx/cyclonedx-library/Models')
const { ComponentType } = require('@cyclonedx/cyclonedx-library/Enums')
const bom = new Bom()
bom.metadata.component = new Component(
ComponentType.Application,
'MyProject'
)
const componentA = new Component(
ComponentType.Library,
'myComponentA',
)
bom.components.add(componentA)
bom.metadata.component.dependencies.add(componentA.bomRef)
```
### 单位 _网页浏览器_
```html
```
## API 文档
我们发送附加说明的类型定义, 这样你的 IDE 和工具可以拿起文档 当你使用这个库下游.
另有在下列网站上寄存的文件: [读取文档](https://cyclonedx-javascript-library.readthedocs.io/)。 。 。 .
## 发展和贡献
随意打开问题,错误报告或调取请求.
见 [捐款](https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/CONTRIBUTING.md) 详细文件.
## 许可证
根据Apache 2.0许可证的规定,允许修改和再分配.
见 [自由主义](https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/LICENSE) 完整许可证存档.
## 常见问题
### @cyclonedx/cyclonedx-library 是什么？
用于JavaScript\(Node\.js或Web Browser\)的CyroundDX核心功能\.
### 如何安装 @cyclonedx/cyclonedx-library？
在项目目录运行 npm install @cyclonedx/cyclonedx-library，或使用 pnpm add / yarn add / bun add。
### @cyclonedx/cyclonedx-library 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @cyclonedx/cyclonedx-library 支持 ESM 还是 CommonJS？
以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。
### @cyclonedx/cyclonedx-library 需要什么版本的 Node\.js？
package\.json 的 engines 字段要求 Node\.js \>=20\.18\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。
### @cyclonedx/cyclonedx-library 可以商用吗？
@cyclonedx/cyclonedx-library 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。
### @cyclonedx/cyclonedx-library 的下载量有多少？
根据 npm 官方下载统计，@cyclonedx/cyclonedx-library 在 2026/10/11 – 2026/11/09 这 30 天内被下载 3,112,600 次，日均约 103,753 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @cyclonedx/cyclonedx-library 还在维护吗？
最新版本 10\.5\.0 发布于 2026/11/09（1 天前）；至今共发布 123 个版本，其中过去 12 个月发布了 18 个；首次发布于 2022/06/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。