XPath 3.1 标准函数库中的 fn:serialize() 专门用来把节点或项序列转换成字符串。要理解它的转换逻辑，要先分清“取节点值”和“序列化节点”这两个动作：string() 返回节点内所有文本的拼接，而 fn:serialize() 会按照 XML 序列化规范重新生成完整的词法表示，包括元素标签、属性、注释和处理指令。这个函数在调试、日志记录、生成请求报文以及把内存中的节点快照持久化成字符串时非常实用。
1. serialize() 与 string() 的区别到底在哪
初次接触这两个函数时，容易混淆 fn:serialize() 和 string()，因为它们都可以接收节点参数。其实二者的目标完全不同。string() 属于数据提取函数，它会把节点转换为 xs:string，具体规则是返回该节点的字符串值：对元素来说就是所有后代文本节点的内容按文档顺序拼接；对属性来说就是属性值；对注释和处理指令不会提取内容。也就是说，string() 只关心“文本”，不关心“结构”。
fn:serialize() 则把节点交给序列化器处理，生成的是 XML 词法表示。除了标签和文本，序列化器还会处理属性引号、命名空间声明、注释、处理指令、CDATA 段等结构。因此同一个节点，string() 可能只返回 XPath 入门，而 fn:serialize() 会返回完整的 XML 片段。
下面的 XPath 表达式可以直观看出差异：假设 $book 绑定到 <book isbn="123"><title>XPath</title></book>，执行 string($book) 的结果是 XPath，执行 fn:serialize($book) 的结果是 <book isbn="123"><title>XPath</title></book>。
string($book) (: 返回 XPath :) fn:serialize($book) (: 返回 <book isbn="123"><title>XPath</title></book> :)
2. 基本调用方式与空序列返回值
fn:serialize() 在 XPath 3.1 函数库中的基础签名是 fn:serialize($arg as item()*) as xs:string?，它还提供一个带第二参数的重载：fn:serialize($arg as item()*, $params as item()?) as xs:string?。第一个参数可以是节点、原子值或任意序列。如果传入的是原子值，函数会先把原子值转换为字符串，再按规则输出；但日常使用中，传入单个元素或文档节点最为常见。
返回值类型是 xs:string?，注意它可能返回空序列。当输入为空序列 () 且未显式设置序列化选项时，fn:serialize(()) 返回的是空序列，而不是空字符串。这个行为在拼接字符串时容易被忽略，比如 concat(fn:serialize($maybe-empty), "end") 在 $maybe-empty 为空序列时可能触发类型错误或返回空序列。如果需要稳定得到空字符串，可以先判断节点是否存在，或者使用支持 allow-empty 选项的实现。
下面是几个不同输入下的返回结果示例，其中 $doc 是一个 XML 文档节点，$book 是它的根元素。
fn:serialize($doc) (: 词法 XML 字符串 :) fn:serialize($doc/book) (: 传入一个元素节点 :) fn:serialize(()) (: 返回空序列，不是空字符串 :) fn:serialize(123) (: 返回 "123" :)
此外，序列化节点时默认不会输出 XML 声明。即使传入的是文档节点，结果通常也直接以根元素开始，例如 <book>...</book>。如果你的管道协议要求带 <?xml version="1.0"?> 声明，就需要通过第二参数把 omit-xml-declaration 设置为 false()。
3. 用第二参数控制缩进、方法和声明
许多场景下的默认序列化结果不够友好，例如不带缩进、使用 XML 输出方法时不保留某些内容。第二参数就是用来控制序列化行为的。在 XPath 3.1 中，这个参数可以是一个 output:serialization-parameters 元素节点；如果所用引擎支持 map 字面量，也可以直接传入一个 map，这也是多数现代处理器推荐的方式。
常见的参数包括 method、indent、encoding、omit-xml-declaration、include-content-type 等。其中 method 决定输出为 xml、html、xhtml、text 或 json（取决于实现）；indent 控制是否添加层级缩进；omit-xml-declaration 控制是否省略 XML 声明。下面示例让节点以 HTML 方式输出并保留缩进。
fn:serialize(
$node,
map {
"method": "html",
"indent": true(),
"omit-xml-declaration": true()
}
)需要特别注意，很多 XPath 实现区分 XML 与 HTML 输出方法。XML 方法会转义所有文本节点中的 < 和 &，而 HTML 方法对 <script> 和 <style> 元素内部的内容采取不同处理，以便于浏览器执行。因此，如果你准备把序列化结果嵌入到 HTML 页面，应优先选择 method=html；如果生成的是通用 XML 报文，则保持默认的 xml 方法更稳妥。
4. 命名空间与调试时的常见坑
节点序列化过程中，命名空间是一个容易产生意外的区域。序列化器通常会在当前元素上输出必要的命名空间节点，但前缀不一定保留原样。比如源节点使用 ns0 前缀，序列化结果可能会变成 Q{http://ipipp.com}book 这种扩展 QName 形式，或者生成 ns1 这样的新前缀。不同引擎的序列化实现可能有所差异，使用时不要依赖前缀名称，而应关注命名空间 URI 是否保持一致。
另一个常见问题是注释与处理指令的呈现。对 string() 来说，注释内容直接消失；但 fn:serialize() 默认会输出 <!--...--> 和 <?...?>。这在调试时很有帮助，因为可以看到完整的节点结构。但在对外接口中，如果不需要注释，最好在序列化前通过 XPath 过滤掉注释节点，例如只选择 //* | //text()，避免无关内容进入最终字符串。
最后，如果你在 XQuery 中使用 fn:serialize()，还要注意某些引擎把它当作“隐式序列化”的一部分。比如 Saxon 对 XQuery 结果会自动序列化，如果查询体里再调用 fn:serialize()，外层输出可能会对字符串再转义一次，导致你看到 <book> 这样的双重转义文本。解决方法是仅在需要字符串值的地方使用该函数，避免多次序列化叠加。
XPath serialize函数节点序列化XPath 3.1修改时间：2026-10-05 04:39:11