xmltodict.unparse() 默认不生成 xml 声明,需显式指定 encoding 参数(如 encoding="utf-8")才会输出 ;full_document 参数控制根元素包裹,与声明无关。

xmltodict.unparse() 默认不生成 XML 声明
调用 xmltodict.unparse() 时,除非显式指定参数,否则输出的字符串**不含 <?xml version="1.0" encoding="utf-8"?> 这类声明**。这是它的默认行为,不是 bug,也不是遗漏。
原因很简单:xmltodict 的设计定位是轻量级 dict ↔ XML 转换,不强制绑定 XML 元信息;XML 声明属于文档级元数据,需要额外控制。
- 如果你直接传入一个 dict 并调用
xmltodict.unparse(my_dict),结果就是纯根元素开始的 XML 片段 - 即使原始 XML 有声明,用
xmltodict.parse()解析后再unparse(),声明也不会自动恢复 - 该函数本身不读取/存储原始 XML 的编码或版本信息,解析时就已丢弃
加 XML 声明必须用 full_document=False + 自行拼接?错,要用 full_document=True 和 encoding 参数
很多人试过 full_document=False 想“手动加声明”,结果发现没用——因为 full_document 控制的是是否包裹顶层 <root></root>,跟 XML 声明无关。
真正起作用的是两个参数组合:
立即学习“Python免费学习笔记(深入)”;
-
full_document=True(默认值,可省略):确保输出是完整文档结构(含根节点),这是生成声明的前提 -
encoding="utf-8"(或其他编码):只要指定了encoding,unparse()就会自动在开头插入对应声明 - 不设
encoding→ 没声明;设了 → 声明按格式自动生成,例如<?xml version="1.0" encoding="gbk"?>
示例:
import xmltodict
data = {"note": {"to": "Tove", "from": "Jani"}}
xml_str = xmltodict.unparse(data, encoding="utf-8")
输出以 <?xml version="1.0" encoding="utf-8"?> 开头。
encoding 参数不只影响声明,还决定实际字节编码和中文处理
设了 encoding 不只是“加一行文字”,它会真实影响字符串内容的编码逻辑:
- 如果 dict 中含中文,且
encoding="gbk",unparse()会尝试用 gbk 编码这些字符(可能抛UnicodeEncodeError) - 若未设
encoding,返回的是 Unicode 字符串,无字节编码动作;但此时也无 XML 声明 - XML 声明中的 encoding 值必须与实际编码一致,否则解析器可能报错或乱码
- Python 3 下推荐统一用
encoding="utf-8",兼容性最好,也最安全
常见错误:用 xmltodict.unparse() 处理已有 XML 声明的输入
如果你从文件读入带声明的 XML,用 xmltodict.parse() 解析后再 unparse(),得到的结果不会“继承”原声明。
- 原声明在 parse 阶段就被忽略,不进 dict 结构,也不存于解析结果的任何字段中
- 所以 unparse 后是否带声明,完全取决于你调用时是否传
encoding - 别指望通过修改 dict 内容来“塞进”声明——XML 声明不属于任何元素,无法映射为 dict key
- 如果必须保留原始声明(比如版本号、standalone 属性),只能自己解析并缓存,再手动拼接
复杂点在于:XML 声明里的 standalone="yes" 或 version="1.1" 这类属性,xmltodict 根本不支持输出,unparse() 只认 encoding 和默认 version="1.0"。










