Oxygen XML Author 是面向 DITA 的专业编辑器，非完整开发环境，需集成 DITA-OT 实现转换；配置须指定正确路径、验证可执行权限并启用插件；DITA Map 必须通过模板创建，主题路径须相对且格式合法；自定义元素需注册 schema 并重启生效。
Oxygen XML Author 本身不是 DITA 开发“环境”，而是面向结构化文档（尤其是 DITA）的专业编辑器；它不编译、不构建、不部署，但能高效编写、验证、预览和协作 DITA 内容。真正完成 DITA 开发闭环，必须配合 DITA-OT（DITA Open Toolkit）和合理项目结构。
怎么配置 DITA-OT 集成到 Oxygen
Oxygen 依赖外部 DITA-OT 实现转换（PDF/HTML5/EPUB 等），不自带完整工具链。配置错误是新手最常卡住的环节。
- 下载匹配版本的
DITA-OT（推荐dita-ot-4.4或dita-ot-4.3，避免用最新 beta 版——Oxygen 25.1 对dita-ot-4.5支持尚不稳定） - 在
Oxygen → Options → Preferences → DITA → DITA Open Toolkit中指定DITA-OT根目录（即含bin/、plugins/的文件夹） - 确认
bin/dita（Linux/macOS）或bin/dita.bat（Windows）可执行；若提示 “DITA-OT not found”，大概率是路径末尾多了斜杠，或权限不足（macOS/Linux 需chmod +x bin/dita） - Oxygen 启动时会在底部状态栏显示
DITA-OT: 4.4 (valid)，否则说明未生效
如何创建合法的 DITA Map 并关联主题
DITA 开发从 .ditamap 文件开始，不是单个 .dita。Oxygen 不会自动帮你补全 <reltable></reltable> 或 <topicref></topicref> 属性，写错就无法解析导航。
- 用
File → New → Framework Templates → DITA → DITA Map创建，别手动建空 XML 文件再改后缀 -
<topicref href="tasks/install_server.dita"></topicref>中的路径必须相对于 ditamap 文件位置，不是相对于 project root；Oxygen 不做路径映射 - 确保引用的
install_server.dita文件存在且根元素为<task></task>（或<concept></concept>/<reference></reference>），否则 Oxygen 校验报Invalid topic type - 不要在
<topicref></topicref>上乱加format="html"——DITA-OT 转换时会忽略，只认format="dita"（默认）或format="markdown"（需插件）
为什么按 F9 生成 PDF 却只弹出空白浏览器窗口
这是 Oxygen 中最典型的“假失败”：表面没报错，实际转换中途静默退出，原因几乎全是 DITA-OT 配置或资源路径问题。
- F9 默认触发
PDF - based on DITA-OT转换场景，但该场景依赖org.dita.pdf2插件是否启用；检查DITA-OT/plugins/下是否存在该文件夹，且plugin.xml中未被注释 - 如果项目用了自定义 CSS（如
custom.css），必须在pdf2/custom.xsl或cfg/fo/attrs/custom.xsl中显式引用，Oxygen 不自动注入 - Windows 用户常见坑：
DITA-OT路径含中文或空格（如C:\Users\张三\tools\dita-ot），会导致 Java 进程启动失败，日志里只显示ERROR: Failed to run transformation，无具体原因 - 查看真实错误：打开
Transformation Scenarios → Edit → Output tab → Check "Show output in console"，重跑 F9，错误堆栈会直接输出在底部控制台
Building file:/C:/work/myproject/map.ditamap [error] Failed to resolve URI 'images/server_arch.png': java.io.FileNotFoundException: C:\work\myproject\images\server_arch.png (The system cannot find the file specified) [error] Transformation failed: java.lang.NullPointerException
怎么让 Oxygen 正确识别自定义 DITA 元素或属性
一旦引入私有 domain（如 <my:step>）或扩展属性（如 audience="admin"），Oxygen 默认不校验也不高亮，需要手动注册 schema 或 grammar。
- 把自定义 XSD 或 RNG 文件（如
my-domain.mod）放到项目catalog.xml可识别的路径下 - 在
Oxygen → Options → Preferences → XML / XML Catalog中添加该catalog.xml，确保其包含类似条目：<uri name="http://www.example.com/dtd/my-domain.dtd" uri="dtd/my-domain.dtd"/> - 在 ditamap 或 dita 文件顶部声明命名空间（RNG）或 DOCTYPE（DTD），例如：
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd" [<!ENTITY % my-domain SYSTEM "my-domain.mod">%my-domain;]> - 重启 Oxygen —— schema 注册不会热加载，不重启无效
DITA 开发中真正的复杂点不在 Oxygen 操作，而在于 DITA-OT 插件行为不可见、domain 扩展缺乏 IDE 级支持、以及 ditamap 导航逻辑必须手写正确。Oxygen 做得最好的是实时验证和所见略同的预览，但别指望它替你理解 chunk 属性怎么影响 HTML 分页，或者 keyref 在多层 map 嵌套中如何解析。
