XML实体引用是XML文档中用来替代重复内容或特殊字符的占位符，当解析器遇到未声明的实体引用时就会抛出未定义错误。要解决这个问题，需要先掌握内部实体和外部实体的声明规则，根据报错场景补充正确的实体声明。
XML实体引用的基本概念
XML中的实体分为预定义实体和自定义实体，预定义实体是XML规范内置的，比如<代表小于号<，&代表&符号，这些不需要额外声明就可以直接使用。而自定义实体需要先声明再引用，否则就会出现未定义的报错。
实体引用的格式是&实体名称;，如果解析器在文档中遇到了这样的格式，但没有找到对应的实体声明，就会抛出类似引用未定义的实体 "xxx"的错误。
内部实体的声明与使用
内部实体是指实体的内容直接定义在XML文档的DOCTYPE声明中，不需要从外部文件加载。内部实体的声明语法如下：
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE 根元素名 [
<!ENTITY 实体名称 "实体内容">
]>
下面是一个内部实体的使用示例，声明了一个名为author的内部实体，然后在文档内容中引用它：
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book [
<!ENTITY author "张三">
<!ENTITY publisher "技术出版社">
]>
<book>
<title>XML入门教程</title>
<author>&author;</author>
<publisher>&publisher;</publisher>
</book>
如果上面的示例中删除了<!ENTITY author "张三">这行声明，解析器遇到&author;时就会提示实体未定义。解决这类问题只需要在DOCTYPE的内部子集中补充对应的实体声明即可。
内部实体的注意事项
- 内部实体的声明必须放在DOCTYPE的内部子集中，也就是
<!DOCTYPE 根元素名 [ ... ]>的中括号内部。 - 实体名称只能包含字母、数字、下划线、冒号和点号，且不能以数字或冒号开头。
- 内部实体的内容可以是文本、特殊字符，甚至是其他已声明的实体的引用，比如
<!ENTITY full_info "&author; 来自 &publisher;">是合法的。
外部实体的声明与使用
外部实体的内容存储在外部的文件中，声明时需要指定外部文件的路径，解析器会在解析时加载外部文件的内容替换实体引用。外部实体的声明语法分为两种，分别对应不同的外部资源类型：
SYSTEM外部实体
SYSTEM外部实体用于引用本地或远程的URI资源，语法如下：
<!ENTITY 实体名称 SYSTEM "资源URI">
比如引用本地的一个文本文件作为实体内容：
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE note [
<!ENTITY content SYSTEM "note_content.txt">
]>
<note>
<content>&content;</content>
</note>
如果note_content.txt文件不存在，或者URI路径错误，解析器可能无法加载到实体内容，也会提示实体相关的错误。如果是远程URI，比如SYSTEM "https://ipipp.com/test.txt"，需要确保网络可访问该地址。
PUBLIC外部实体
PUBLIC外部实体用于引用公共的实体标识，通常配合SYSTEM的URI作为 fallback，语法如下：
<!ENTITY 实体名称 PUBLIC "公共标识" "资源URI">
公共标识一般是遵循特定规范的字符串，比如引用一个公共的DTD文件：
<!ENTITY mydtd PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "https://ipipp.com/xhtml1-strict.dtd">
外部实体的常见问题与解决
- 如果提示外部实体未定义，首先检查DOCTYPE中是否有对应的外部实体声明，确认实体名称拼写正确。
- 如果提示无法加载外部实体，检查SYSTEM后面的URI是否正确，本地文件是否存在，远程地址是否可访问，同时注意部分解析器默认会禁止加载外部实体，需要开启对应的解析选项。
- 避免外部实体路径使用相对路径时出现位置偏差，尽量使用绝对路径或者明确的相对路径基准。
实体引用未定义的通用排查步骤
当遇到XML实体引用未定义的报错时，可以按照以下步骤排查：
- 确认报错的实体名称，检查文档中是否有对应的
<!ENTITY>声明，包括内部实体和外部实体。 - 如果是内部实体，检查声明是否在DOCTYPE的内部子集中，实体名称是否和引用时完全一致，包括大小写。
- 如果是外部实体，检查SYSTEM或PUBLIC的声明是否存在，URI路径是否正确，外部资源是否可访问。
- 检查是否存在实体声明顺序问题，比如实体A引用了实体B，那么实体B的声明必须放在实体A之前。
- 确认解析器是否支持对应的实体类型，部分简化版XML解析器可能不支持外部实体，需要更换解析器或者改用内部实体。
实体声明的安全注意事项
在使用外部实体时需要注意XXE（XML外部实体注入）安全风险，恶意用户可能通过构造外部实体读取服务器上的敏感文件。如果不需要使用外部实体，建议在解析XML时禁用外部实体加载功能。比如在Java中使用DocumentBuilderFactory时，可以通过以下设置禁用外部实体：
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.DocumentBuilder;
import org.w3c.dom.Document;
public class XmlParser {
public static void main(String[] args) throws Exception {
DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
// 禁用外部实体
dbf.setFeature("http://xml.org/sax/features/external-general-entities", false);
dbf.setFeature("http://xml.org/sax/features/external-parameter-entities", false);
dbf.setXIncludeAware(false);
dbf.setExpandEntityReferences(false);
DocumentBuilder db = dbf.newDocumentBuilder();
Document doc = db.parse("test.xml");
}
}
合理声明和使用XML实体，既能提高XML文档的编写效率，也能避免解析错误和安全问题。遇到实体未定义的报错时，优先检查实体声明是否完整、路径是否正确，基本可以快速定位问题根源。
XMLEntity_Reference内部实体外部实体实体声明修改时间：2026-07-04 14:36:38