Erlang/OTP 28.0-rc版本文档构建失败问题分析

在Erlang/OTP 28.0-rc版本的构建过程中，部分用户遇到了文档构建失败的问题。这个问题主要出现在使用Nix构建系统时，具体表现为在生成HTML文档时ex_doc工具将警告视为错误导致构建中断。

问题的根本原因在于28.0-rc版本中更新了ex_doc工具版本，新版本对文档链接检查更加严格。当构建环境中缺少某些模块（如jinterface和odbc）时，ex_doc会检测到这些模块文档的链接失效并产生警告。由于构建配置默认将警告视为错误，最终导致构建过程失败。

对于这个问题，开发团队提供了几种解决方案：

1. 临时解决方案是在构建文档时设置环境变量EX_DOC_WARNINGS_AS_ERRORS=false，这样即使出现链接警告也不会中断构建过程。

2. 更合理的长期解决方案是调整文档构建目标。对于大多数用户场景，实际上并不需要构建完整的HTML文档，只需要构建chunks（供IDE使用）和man pages（手册页）即可。可以通过设置DOC_TARGETS="chunks man"来实现这一目的。

3. 开发团队还计划在代码层面进行改进，当检测到某些应用模块未被构建时，自动禁用将警告视为错误的设置，从而提高构建系统的健壮性。

这个问题也反映出在构建配置上的一些最佳实践：在自动化构建环境中，应当仔细考虑实际需要的文档类型，避免构建不必要的文档目标。同时，构建系统应当能够智能处理部分模块缺失的情况，而不是简单地失败。

对于使用Nix等打包系统的用户，建议评估实际文档需求，合理配置DOC_TARGETS参数，这样既能满足使用需求，又能简化构建过程并提高成功率。