# @federicocarboni/saxe 中文文档

规范地址：https://npmcn.com/package/%40federicocarboni/saxe/

版本：0\.8\.0
npm 元数据更新时间：2025-12-03T21:08:36.420Z
中文译文更新时间：2026-11-14T13:07:42.783Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：273 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-10-14T15:37:15.523Z
- 最新版本发布：2025-12-03T21:08:36.204Z
- 近 30 天下载量：3385（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 1 个）

## 中文简介

轻量级和高效的 SAX 风格的 XML 解析器

## 安装

```sh
npm install @federicocarboni/saxe
```

也可以使用：`pnpm add @federicocarboni/saxe`、`yarn add @federicocarboni/saxe`、`bun add @federicocarboni/saxe`

## README

# 萨克森州

[![Docs](https://img.shields.io/badge/docs-online-brightgreen)](https://federicocarboni.github.io/saxe/) [![Coverage](https://img.shields.io/codecov/c/github/federicocarboni/saxe?logo=codecov)](https://app.codecov.io/gh/federicocarboni/saxe) [![Bundle size](https://edge.bundlejs.com/badge?q=@federicocarboni/saxe)](https://bundlejs.com/?q=@federicocarboni/saxe)

JavaScript的轻量级和高效的SAX型XML分解器.

## 目标

-   完全 XML 1.0 和 Namespaces 在 XML 1.0 标准符合性中
-   简单和三角形 API
-   减少代码脚印
-   设定基于 XML (例如 XHTML) 的其他标准的基础

### 非目标

-   XML DTD 验证
-   DOM 全面执行
-   语法错误容忍度
-   源代码分析或 LSP 特性

#### XML 1.1 和 XML 1.1 中的命名空间

XML 1.1和取名空间在XML 1.1中不支持. 宣布版本的文件 `1.1` 解析为 XML `1.0`,所以特性为版本专用 `1.1` 没有 承认.

现代的UTF-8网页内容完全是XML 1.0,这使得XML 1.1及其 命名空间大多无关紧要.

XML 1.1几乎完全用于遗产或专门环境下,因为其 特殊特点和更好的EBCDIC支持可能是有用的。 见 [XML - 维基百科 § 第1.0和1.1版](https://en.wikipedia.org/wiki/XML#1.0_and_1.1)。 。 。 .

## 示例

```js
import {SaxParser} from "@federicocarboni/saxe";

const parser = new SaxParser({
  startTag(name, attributes) {
    // Start tag: example
    // Start tag: empty-tag [attr, value]
    console.log("Start tag:", name, ...attributes);
  },
  endTag(name) {
    // End tag: example
    // End tag: empty-tag
    console.log("End tag:", name);
  },
  text(content) {
    // Text: Hello, world!
    console.log("Text:", content);
  },
});
parser.parse("<example>Hello, world!", {stream: true});
parser.parse(`<empty-tag attr="value" />`, {stream: true});
parser.parse("</example>");
```

## 运行时间支持

-   Basic XML 解析:任意ES2017运行时间. 对于更早的运行时间 转接和 多填充应该足够了.

## 文件类型声明

许多\[^1\] JavaScript XML 解析器简化了内部 DTD 子集的处理, 要么不检查其造型良好,要么无视其声明.

内部的 DTD 子集解析即使是对非验证 \[^2\] 处理器也是需要的, 此解析器执行整个规格 :

-   内部的 DTD 子集被解析并检查其造型良好.
-   `ATTLIST` 声明被承认适用正常化和默认 值为属性.
-   `ENTITY` 宣言被确认用于扩大实体的参考.

这个过程 [所涉安全问题](https://npmcn.com/package/%40federicocarboni/saxe/#readme-security);所以 DTD 处理可以是 通过配置启用 [`SaxOptions.dtd`](https://federicocarboni.github.io/saxe/interfaces/SaxOptions.html#dtd)。 。 。 .

外部加价申报和外部实体不需要 非验证 \[^2\] 处理器,并明确不支持.

## 警卫

XML 解析器可能有一些可能的脆弱性,最常见的是 攻击利用外部实体的分辨率和实体扩展.

这个解析器严格来说是不验证的 所以设计上它不应该是脆弱的 用于任何基于XXE\[^3\]的攻击。 此外,在 解析以限制其他拒绝服务攻击的功效\[^4\].

根据OWASP的建议,默认禁止DTD处理.

```js
new SaxParser(handler, {
  // Reject any DOCTYPE declaration
  dtd: "prohibit", // default
  // Alternatively, allow it but ignore any declarations
  // dtd: "ignore",

  // Enforce stricter limits over strings and values
  // collected during parsing.
  maxAttributesLength: 10000,
  maxElementDepth: 30,
  maxEntityDepth: 5,
  maxEntityLength: 1000,
  maxNameLength: 500,
  maxTextLength: 10000,
})
```

[已知的 XML 炸弹](https://npmcn.com/test/data/) 测试作为定期整合的一部分 测试和解析器是 [测试模糊度](https://npmcn.com/fuzz/) 经常 虽然如此 对于非常明智或面向安全的应用程序,您可能想要执行您的 自己的安全审计.

\[^1\]:检查过的其他JavaScript XML解析器包括: [isaacs/ sax-js (英语)](https://github.com/isaacs/sax-js), (中文(简体) ), [自然情报/快速Xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser) 财务报告和审定财务报表 [lddubeau/ 轴](https://github.com/lddubeau/saxes) \[^2\]: XML 处理器(parsers)不验证文档,但 还必须识别并报告成型良好的(语法)错误. 不验证的处理器不需要获取和剖析外部标记 声明和外部实体. [XML 标准 第5.1条 验证和非验证处理器](https://www.w3.org/TR/REC-xml/#proc-types) \[^3\]: [XML 外部实体(XXI) 处理 OWASP基金会](https://owasp.org/www-community/vulnerabilities/XML_External_Entity_\(XXE\)_Processing) \[^4\]: [XML 拒绝服务攻击和防卫 微软学习](https://web.archive.org/web/20240318075117/https://learn.microsoft.com/en-us/archive/msdn-magazine/2009/november/xml-denial-of-service-attacks-and-defenses)

## 许可证

根据Apache许可证第2.0版获得许可. 参见 LICENSE 文件 细节.

## 常见问题

### @federicocarboni/saxe 是什么？

轻量级和高效的 SAX 风格的 XML 解析器

### 如何安装 @federicocarboni/saxe？

在项目目录运行 npm install @federicocarboni/saxe，或使用 pnpm add / yarn add / bun add。

### @federicocarboni/saxe 支持 TypeScript 吗？

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

### @federicocarboni/saxe 支持 ESM 还是 CommonJS？

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

### @federicocarboni/saxe 可以商用吗？

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

### @federicocarboni/saxe 的下载量有多少？

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

### @federicocarboni/saxe 还在维护吗？

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