Python lxml etree.tostring encoding 生成带编码声明的XML字节流

etree.tostring() 的 encoding 参数仅控制字节流编码格式，不自动插入 encoding 声明，必须显式指定 xml_declaration=true 才能生成带编码声明的 xml 字节流。

etree.tostring() 默认不写编码声明，哪怕指定了 encoding 参数

这是最常被误解的一点：etree.tostring() 的 encoding 参数只控制输出字节流的编码格式（比如 b'<?xml version="1.0" encoding="utf-8"?>...' 还是 b'<?xml version="1.0"?>...'），但**不会自动插入 encoding="..." 声明**——除非你显式传入 xml_declaration=True。

常见错误现象：用 etree.tostring(root, encoding="utf-8") 得到的字节流开头是 b'<?xml version="1.0"?>'，没有 encoding 属性，导致某些 XML 解析器报 UnicodeDecodeError 或警告“encoding mismatch”。

• xml_declaration=True 是必须加的开关，它才真正触发编码声明生成
• encoding 参数必须是字符串（如 "utf-8"、"iso-8859-1"），不能是 None 或 bytes
• 如果 encoding="unicode"，结果是字符串而非字节流，此时 xml_declaration 无效（因为声明只存在于字节流中）

生成带 UTF-8 声明的字节流：正确调用方式

要得到 b'<?xml version="1.0" encoding="utf-8"?>...，必须同时满足两个条件：指定字节编码 + 启用 XML 声明。

正确示例：

立即学习“Python免费学习笔记（深入）”；

from lxml import etree root = etree.XML("<root><child>café</child></root>") data = etree.tostring(root, encoding="utf-8", xml_declaration=True) # → b'<?xml version="1.0" encoding="utf-8"?><root><child>café</child></root>'

• 缺 xml_declaration=True → 没有 encoding="utf-8" 声明，只有 b'<?xml version="1.0"?>...'
• 缺 encoding 参数或设为 "unicode" → 返回 str，无法写入二进制文件，且无声明
• encoding 设为 "us-ASCII" 但内容含非 ASCII 字符 → 抛 UnicodeEncodeError，不是静默截断

encoding 参数值影响实际输出和兼容性

encoding 不只是“告诉 lxml 用什么编码”，它还决定了字节流能否被下游系统安全消费。例如 windows 记事本默认用 GBK 解析无 bom 的 UTF-8 文件，若你输出 UTF-8 字节流却不带声明，它很可能乱码。

• encoding="utf-8"：最通用，但需搭配 xml_declaration=True 才能被多数解析器识别为 UTF-8
• encoding="utf-8-sig"：lxml 不支持该值，会报 LookupError；BOM 需手动添加（不推荐）
• encoding="iso-8859-1"：适合老系统，但中文等字符会直接失败，报 UnicodeEncodeError
• 避免用 encoding=None：等价于 "unicode"，返回字符串，不是字节流

写入文件时容易漏掉的一步：别用 text 模式写 bytes

拿到 etree.tostring(..., encoding="utf-8", xml_declaration=True) 返回的是 bytes，但很多人直接用 open("out.xml", "w").write(data)，这会抛 TypeError: write() argument must be str, not bytes。

• 写二进制文件必须用 "wb" 模式：open("out.xml", "wb").write(data)
• 如果坚持用文本模式（比如想换行符标准化），得先解码成 str，但那就失去了 xml_declaration 的意义——因为 str 没有编码声明概念
• 用 with 确保文件关闭：with open("out.xml", "wb") as f: f.write(data)

XML 声明是否出现、内容是否匹配实际字节编码，这两个点必须同步控制；少一个，下游就可能出错，而且错误位置往往不在生成端，而在读取端，排查起来更绕。