XML Catalog 是 OASIS 标准机制，用于将 XML 中外部资源（如 DTD、XSD）的 URI 映射到本地路径，避免网络加载或路径错误；通过 system、public、rewriteSystem 等标签定义重写规则，需在解析器中显式启用。
XML Catalog 是什么，它解决什么问题
XML Catalog 是一种标准化的机制（OASIS 标准），用来将 XML 文档中引用的外部资源（比如 DOCTYPE 声明里的 DTD、xsi:schemaLocation 或 xsi:noNamespaceSchemaLocation 中的 XSD）**映射到本地文件路径**，从而避免解析器去网络加载（如 http://www.w3.org/2001/XMLSchema.xsd）或因路径错误而报错。
它不改变 XML 本身，而是作为解析器的“重写规则表”——当解析器看到一个公共 ID（PUBLIC）或系统 ID（SYSTEM），就查 catalog 文件，用本地路径替换掉原始 URI。
如何写一个基本的 catalog.xml 文件
最常用的是 OASIS XML Catalog 格式。以下是一个典型例子，用于把 W3C 的 XSD 和自定义 DTD 映射到本地：
关键点：
-
system标签匹配完整的systemId字符串（如 DTD 的 SYSTEM 引用） -
public标签匹配 DOCTYPE 中的PUBLIC "..." "..."第一个字符串（即公共标识符） -
rewriteSystem是通配匹配：所有以https://example.com/schemas/开头的系统 ID，都会被替换成local-schemas/开头的路径 -
uri值必须是相对路径（相对于 catalog 文件所在目录）或绝对路径；不支持file://协议前缀（多数解析器会忽略或报错）
Java SAX/DOM 解析器如何启用 catalog 支持
标准 JAXP（javax.xml.parsers）不原生支持 catalog。必须借助第三方库，最常用的是 org.apache.xml.resolver（Apache XML Commons Resolver）。
启用步骤：
- 添加依赖：
xmlresolver（Maven artifact ID：xml-commons-resolver） - 创建
CatalogResolver实例，并指向你的catalog.xml - 将该 resolver 设置给
SAXParserFactory或DocumentBuilder
示例（SAX）：
SAXParserFactory factory = SAXParserFactory.newInstance();
CatalogManager manager = new CatalogManager();
manager.setCatalogFiles("catalog.xml");
manager.setIgnoreMissingProperties(true);
CatalogResolver resolver = new CatalogResolver(manager);
XMLReader reader = XMLReaderFactory.createXMLReader();
reader.setEntityResolver(resolver); // 关键：设置 resolver
reader.setContentHandler(new MyHandler());
reader.parse(new InputSource("test.xml"));
注意：
- 如果解析器抛出
java.io.FileNotFoundException找不到 DTD/XSD，大概率是 catalog 没生效，先确认setEntityResolver被正确调用 - JDK 自带的
com.sun.org.apache.xml.internal.resolver是内部类，不建议直接依赖 - 不要试图用
System.setProperty("xml.catalog.files", "...")—— 这仅对某些老版本 Apache Xerces 有效，且已被弃用
Python lxml 如何使用 catalog（libxml2 backend）
lxml 底层用 libxml2，它原生支持 catalog，但默认不启用。需手动配置环境变量或调用 API。
推荐方式是设置环境变量（在 Python 进程启动前）：
import os os.environ['XML_CATALOG_FILES'] = '/path/to/catalog.xml' # Linux/macOS # 或 Windows：os.environ['XML_CATALOG_FILES'] = 'C:\\path\\to\\catalog.xml'
然后正常解析即可：
from lxml import etree parser = etree.XMLParser(dtd_validation=True, no_network=True) tree = etree.parse('test.xml', parser)
关键参数说明：
-
no_network=True强制禁用网络请求（否则即使有 catalog，libxml2 仍可能 fallback 到网络） -
dtd_validation=True或schema=...才会触发 catalog 查找 - 路径分隔符：Windows 下多个 catalog 用分号
;，Linux/macOS 用空格 - libxml2 不支持
rewriteSystem，只认system和public；若需通配，改用delegateSystem（需更严格匹配前缀）
catalog 生效与否，最直接验证方式是开启调试：XML_DEBUG_CATALOG=1 环境变量，运行时会打印匹配过程。
真正麻烦的不是写 catalog，而是确保解析器链路每一步都接上了它——从环境变量、工厂设置、到 parser 实例，任何一环漏掉，就退回网络加载或报错。
