DocBook XML 是语义化结构化标记规范，需经验证→转换→渲染生成可用格式；非即用文件，须用工具链处理，常见失败源于编码、DOCTYPE错配及路径问题。
什么是 DocBook XML：不是文件类型，是写作契约
DocBook XML 是由 OASIS 维护的一套 DTD 或 XML Schema（如 docbook-xsl-ns-1.79.1），定义了像 <book>、<chapter>、<para>、<programlisting> 这类标签的合法嵌套规则和语义含义。它不关心样式，只管“这是标题还是代码块”，把内容结构和呈现彻底分开。
你写的 mydoc.xml 本质是一个「结构说明书」，不是成品——就像建筑师的蓝图，不能直接住人。
- ✅ 正确理解：它是可被工具链消费的中间格式，目标是“一份源码，多端输出”（HTML/PDF/CHM/EPUB）
- ❌ 常见误解：把它当成 Word 或 Markdown 那样“双击打开就能看”，结果用浏览器直接打开只看到满屏 XML 标签甚至报错
- ⚠️ 注意：DocBook 4.x（基于 DTD）和 DocBook 5.x（基于 RELAX NG / XML Schema）不兼容，选错 DTD 或 XSL 样式表会导致
xsltproc报validation failed或静默失败
如何上传并处理：关键在“处理”，不在“上传”
所谓“上传”，通常指把 XML 源文件放入构建环境（如 CI 服务器、本地工作目录），然后调用转换工具链。没有统一“上传接口”，只有明确的命令流程。
以 Ubuntu/Debian 环境为例，最小可行闭环如下：
xsltproc --nonet --xinclude -o mydoc.html /usr/share/xml/docbook/stylesheet/docbook-xsl/html/chunk.xsl mydoc.xml fop -xml mydoc.fo -pdf mydoc.pdf
但这里有两个隐藏前提必须满足：
-
mydoc.xml必须通过 DTD 或 Schema 验证（用xmllint --valid --noout mydoc.xml测） -
chunk.xsl路径要对——不同发行版路径差异大：/usr/share/docbook-xsl/、/usr/share/xml/docbook/stylesheet/docbook-xsl/、甚至/opt/docbook-xsl/都可能 - 中文支持需额外配置：
--stringparam html.stylesheet docbook.css+ CSS 中加body { font-family: "Noto Sans CJK SC", sans-serif; }，否则 PDF 里汉字变方框
常见失败点：XML 合法性、编码、路径全军覆没
90% 的“处理失败”其实卡在最基础层，不是 XSL 写错，而是 XML 本身就不合格。
-
编码陷阱：文件保存为 UTF-8 但没写声明，或声明了
encoding="UTF-8"却实际存成 GBK ——xsltproc会直接崩溃并报Input is not proper UTF-8 -
DOCTYPE 错配：用 DocBook 5.x 的 XML（带
xmlns="http://docbook.org/ns/docbook"）却引用 DocBook 4.4 的 DTD（docbookx.dtd），解析器直接拒收 -
相对路径失效：XML 里写
<imagedata fileref="images/fig1.png"/>，但执行xsltproc时当前目录不是 XML 所在目录，图片就消失；建议统一用--path ./images或改用绝对路径变量 -
XSL 引用错位：DocBook 5.x 必须用带
-ns后缀的样式表（如docbook-xsl-ns-1.79.1），用老版本会跳过所有命名空间元素，输出空白 HTML
要不要自己搭？推荐用现成 Docker 或 GitHub Action
手动装 docbook-xsl、fop、saxon、字体、中文字体配置……容易陷入依赖地狱。真实项目中更可靠的做法是复用封装好的构建环境。
- Docker：官方镜像
docbook/docbook-xsl或自建含fop+ Noto Sans CJK 的镜像，docker run -v $(pwd):/docs docbook/docbook-xsl xsltproc ... - GitHub Actions：用
actions/setup-java+actions/setup-python配好 FOP 和 XSLT 工具链，PR 提交后自动产出 PDF/HTML 并上传到 release - 本地快速验证：用
xmlcopyeditor（Linux）或Oxygen XML Editor（跨平台），它们内置验证+预览，比命令行快十倍定位问题
.xml 在 xmllint 下不报错、在 xsltproc 下不空转、在 PDF 里汉字不丢——这三关过了，后面只是复制粘贴命令的事。 
