DITA-OT 3.6转HTML5随机缺失输出文件问题求助

问题情况 #

• 环境：Windows系统 + DITA-OT 3.6
• 核心现象：18个.dita主题组成的文档转PDF完全正常，但转HTML5时每次随机缺失1-3个.html文件，且每次缺失的文件不固定；重复执行完全相同的构建命令，结果仍不一致
• 日志报错：html5.topics.common阶段显示缺失文件对应错误：[xslt] Failed to transform document: Failed to transform document: Failed to create directory <filepath of output html directory>.，但报错指定的目录实际已存在，且目录下有其他成功生成的.html文件
• 附加信息：OxygenXML检查所有主题无语法、字符或属性异常；temp目录中保留了所有源.dita文件（包括对应缺失输出的文件）；多次重复构建可凑齐完整输出文件，但不符合生产需求

可能原因 #

DITA-OT 3.6默认开启的**并行构建（多线程处理）**在Windows平台存在目录操作的竞态条件：多个线程同时尝试访问同一输出目录时，会出现"目录是否存在"的判断逻辑冲突，部分线程误判目录未创建，进而抛出错误终止该文件的转换流程。

解决方案 #

1. 临时禁用并行构建（快速验证） #

在构建命令中添加-Dparallel=off参数强制单线程处理，避免多线程竞争问题：

dita --input=你的地图文件.ditamap --format=html5 -Dparallel=off

如果单线程构建后不再缺失文件，即可确认是并行处理的竞态问题导致的故障。

2. 升级DITA-OT版本（彻底解决） #

DITA-OT 3.6之后的版本（尤其是4.x系列）修复了Windows平台下多个并行构建相关的缺陷，包括目录操作的竞态问题。升级时需注意：

• 备份当前自定义插件、转换配置文件（如custom.xml或自定义参数集）
• 优先选择最新稳定版（如4.1及以上），确保兼容性
• 升级后测试原有构建命令和自定义配置，部分旧版参数可能在新版中有调整

3. 调整输出目录权限与路径 #

避免因Windows权限或受保护路径导致的文件写入异常：

• 确认输出目录所在路径不属于系统受保护目录（如C:\Program Files），建议放在用户个人目录下（如C:\Users\你的用户名\Documents\dita-output）
• 右键输出目录 → 属性 → 安全，确保当前用户拥有读取、写入、修改的完全权限

4. 清理临时目录后重新构建 #

残留的临时文件可能干扰构建流程，可手动或自动清理：

• 手动删除DITA-OT临时目录：默认路径为%USERPROFILE%\AppData\Local\Temp\dita
• 或在构建命令中添加参数自动清理：

  dita --input=你的地图文件.ditamap --format=html5 -Dclean.temp=yes
  

验证步骤 #

1. 先使用禁用并行构建的命令测试，确认问题是否消失
2. 若确认是并行处理问题，可选择长期使用单线程构建，或升级DITA-OT版本恢复并行效率

内容的提问来源于stack exchange，提问作者Helena Nash