XML处理指令（PI）是供特定应用程序读取的元信息，语法为，必须位于XML声明后、根元素前；其生效依赖目标解析器是否支持对应target，而非语法正确性。

XML处理指令（Processing Instruction，简称 PI）是嵌入在 XML 文档中、不参与文档结构解析，但可被特定应用程序读取并执行的元信息指令。它不是元素，也不是属性或注释，而是一种“给处理器看的便签”。

---

怎么写一个合法的处理指令？

语法固定为：<?target instruction?>，其中：

• target 是目标名，必须以字母或下划线开头，不能是 xml（大小写敏感，XML、Xml 也不行）
• instruction 是任意字符串，可含空格、引号、等号，甚至未转义的 或 <code>& —— XML 解析器不会解析它，只原样传递
• 必须成对出现：开头 ，结尾 ?>，中间不能换行

常见合法示例：

<?xml-stylesheet type="text/xsl" href="style.xsl"?><?app-config mode="debug" timeout="3000"?><?custom-log enabled="true" level="verbose"?>

---

放在哪儿才有效？

处理指令可以出现在 XML 文档的多数位置，但有隐含优先级和兼容性陷阱：

java-api-doc-generator

分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。

下载

• 最安全的位置是：紧跟在 <?xml version="1.0" encoding="UTF-8"?> 之后、根元素之前 —— 这是 XSLT、浏览器、大多数 XML 工具默认识别的“序言区”
• 理论上可插入到元素之间、文本节点前后，甚至根元素内部（如 <root><?my-pi ?></root>），但很多工具（如 .NET 的 XDocument、Java 的 DOMParser）默认不保留内部 PI，或忽略它们
• 绝不能出现在 XML 声明之前，也不能在注释或 CDATA 区内

---

为什么写了却没生效？

常见失效原因不是语法错，而是目标程序根本不处理它：

• <?xml-stylesheet ...?> 只在浏览器打开 XML 文件，或支持 XSLT 的解析器中触发；用 Python 的 xml.etree.ElementTree 读取时，这个 PI 默认被丢弃（除非显式启用 parser.target 捕获）
• target 名字拼错（比如写成 xml-style-sheet）或大小写不符（XML-STYLESHEET ≠ xml-stylesheet）
• 某些 XML 编辑器（如 VS Code 默认 XML 插件）会自动过滤或隐藏 PI，导致你以为“没加进去”
• 如果文档用了 DTD 或 XSD 验证，PI 不影响验证结果 —— 但它本身不参与任何校验，所以也不会报错

---

C# / Python 中怎么安全插入和读取？

语言原生 API 对 PI 支持差异大，别假设“写进去就能读出来”：

• C# 的 XDocument：用 XDocument.AddFirst(new XProcessingInstruction("target", "data")) 可插入；读取需遍历 Nodes() 并筛选 XProcessingInstruction 类型节点
• Python 的 xml.etree.ElementTree：默认完全忽略 PI；必须用 XMLParser(target=TreeBuilder()) 自定义 parser，或改用 lxml.etree（支持 parser.set_element_class_lookup() 捕获 PI）
• Java 的 DocumentBuilder：需设置 setIgnoringElementContentWhitespace(false) 并手动检查 Node.getNodeType() == Node.PROCESSING_INSTRUCTION_NODE

真正容易被忽略的一点：处理指令不是“配置开关”，而是“信号弹”——发出去谁接、怎么接、接了干啥，全由下游程序自己决定。没有通用语义，也没有强制约定。 写之前，先确认你的目标解析器文档里有没有明确说它支持哪个 target。