lxml.etree.Element 比所谓“Builder”更常用，因为lxml没有原生Builder类；开发者手动封装的链式调用非官方支持，而直接使用etree.Element和etree.SubElement更稳定、兼容、易调试。
lxml.etree.Element 为什么比 Builder 更常用
因为 lxml 本身没有叫 Builder 的内置类——你查文档、搜 GitHub、看 Stack Overflow，都找不到官方 lxml.builder 模块。所谓“Builder 模式”，其实是开发者用 etree.Element 和 etree.SubElement 手动组装节点时，模仿 Java 或 C# 风格写出来的链式调用封装，不是 lxml 原生支持的机制。
直接用原生 API 反而更稳：省去中间抽象层、不引入额外依赖、调试时堆栈清晰、兼容所有 lxml 版本（包括旧版 4.x 和新版 5.x）。
- 别 pip install lxml-builder —— 不存在这个包
- 别照搬 Java 的
new XmlBuilder().addTag("a").text("b")写法，lxml 不认 - 如果看到别人写了
XmlBuilder类，那一定是他们自己写的工具类，不是 lxml 的一部分
用 etree.SubElement 构建嵌套结构最不容易错
新手常试图用字符串拼接或反复调用 etree.Element 创建子节点，结果父节点没保存引用、子节点丢失、命名空间错乱。正确做法是始终用 etree.SubElement 显式挂载，并复用父节点变量。
比如生成 <root><child id="1">text</child></root>：
立即学习“Python免费学习笔记（深入）”；
from lxml import etree
<p>root = etree.Element("root")
child = etree.SubElement(root, "child", id="1")
child.text = "text"</p><h1>✅ 正确：child 是 root 的真实子节点</h1><h1>❌ 错误：etree.Element("child") 独立存在，没加进 root</h1><p>- 所有子节点必须通过
etree.SubElement(parent, tag, **attrib)注册到父节点 -
text和tail属性要显式赋值，不会自动继承或推导 - 如果需要批量添加同级节点，用循环 +
SubElement，别反复root.append(...)—— 后者效率略低且易漏类型检查
命名空间和前缀必须在创建根节点时声明
等你加上 xmlns 或带前缀的标签（比如 <soap:Envelope>），再补命名空间就晚了。etree.Element 的 nsmap 参数只在初始化时生效，后续调用 SubElement 不会自动继承或合并。
常见错误现象：lxml.etree.XMLSyntaxError: Namespace prefix soap for Envelope is not defined
NSMAP = {"soap": "http://schemas.xmlsoap.org/soap/envelope/"}
root = etree.Element("{http://schemas.xmlsoap.org/soap/envelope/}Envelope", nsmap=NSMAP)
body = etree.SubElement(root, "{http://schemas.xmlsoap.org/soap/envelope/}Body")
<h1>✅ 正确：每个带命名空间的 tag 都要用完整 URI 包裹（或用 makeelement）</h1><h1>❌ 错误：写成 "soap:Envelope" —— lxml 不解析前缀，只认 URI</h1><p>- 别在 tag 字符串里写冒号前缀（如
"soap:Envelope"），lxml 不识别这种语法 - 推荐用
"{URI}LocalName"格式，或配合etree.QName构造带命名空间的标签名 - 如果 XML 要输出前缀（如
soap:Envelope），必须在nsmap中声明对应前缀，否则序列化时可能变成无前缀的长 URI
tostring() 默认不缩进，pretty_print=True 有编码陷阱
生成完树，调 etree.tostring(root) 得到的是单行字节流，看着不像 XML。加 pretty_print=True 能美化，但容易踩两个坑：一是返回 bytes 而非 str，二是默认编码为 UTF-8，若你手动 decode 成 str 再写入文件，可能触发重复解码错误。
# ✅ 安全写法：指定 encoding 并保持 bytes 流向
xml_bytes = etree.tostring(root, encoding="utf-8", pretty_print=True)
with open("out.xml", "wb") as f:
f.write(xml_bytes)
<h1>❌ 危险写法：</h1><p>xml_str = etree.tostring(root, pretty_print=True).decode("utf-8") # 多余 decode
-
pretty_print=True会显著降低性能，生成大 XML（>10MB）时建议关掉 - 如果需控制缩进宽度，lxml 不支持直接设 indent=2；得用
etree.indent(root, space=" ")（lxml ≥ 4.5.0），且必须在tostring前调用 - 中文 text 内容无需额外处理编码，lxml 内部统一用 Unicode，只要输入是 str 就行
实际用的时候，最麻烦的从来不是怎么拼标签，而是命名空间对不上、text 被空格吞掉、或者 tostring 返回 bytes 却当 str 用了——这些地方一卡就是半小时。
