Swift-Book 项目构建问题分析与解决方案

问题背景

在使用 Xcode 15.3 的 docc 工具构建 Swift-Book 项目时，开发者遇到了构建失败的问题。具体表现为执行 xcrun docc preview TSPL.docc 命令时出现 zsh: trace trap 错误，这是一个比较模糊的错误提示。

问题根源分析

经过深入调查，发现这个问题与 DocC 工具在不同 Swift 版本中的行为差异有关：

1. Swift 5.10 版本的 DocC 存在一些问题，特别是与未解析链接相关的处理逻辑不够健壮，导致在构建这本书时会出现崩溃。

2. 诊断格式化器问题：Swift 5.10 版本引入了一个新的诊断格式化器，用于在命令行中显示诊断信息。这个格式化器会从源文件中读取代码行来高亮显示诊断范围。初始实现假设诊断范围在源文件中总是有效的，如果范围不存在就会导致越界崩溃。

3. 标记语法冲突：DocC 添加了双反引号语法用于 API 链接，这与 Markdown 中用于包含反引号的代码语音语法产生了冲突，导致了一些警告信息。

解决方案

针对这个问题，开发者可以采取以下几种解决方案：

1. 使用特定版本的 DocC

• 推荐使用 Swift 5.9 版本的 DocC：这是构建 Swift 5.10 版本书籍时使用的工具，已知能够正常工作。
• 从源码构建最新版 DocC：从主分支构建的 DocC 在发布模式下可以正常工作，但在调试模式下仍会因断言失败而崩溃。

2. 使用命令行参数

在命令中添加 --ide-console-output 参数可以绕过新的诊断格式化器，使用更适合工具或脚本解析的诊断格式化器：

xcrun docc preview TSPL.docc --ide-console-output

3. 处理警告信息

构建过程中可能会出现一些关于反引号的警告信息，这些是由于 DocC 的双反引号语法与 Markdown 代码语音语法的冲突造成的。虽然这些警告不会影响构建结果，但开发者应该了解它们的来源：

• 在 Markdown 中，使用双反引号可以包含带有反引号的代码片段（如 `class`）
• DocC 会将这些双反引号内容误认为是 API 链接尝试，因此产生警告

最佳实践建议

1. 版本选择：对于稳定的构建环境，建议使用经过验证的 DocC 版本（如 Swift 5.9 版本）。

2. 开发环境：如果需要在最新环境下工作，可以从源码构建 DocC 的主分支版本，并使用发布模式而非调试模式。

3. 构建命令：在不确定的情况下，始终添加 --ide-console-output 参数以避免潜在的格式化器崩溃问题。

4. 警告处理：对于文档中的代码语音标记警告，可以暂时忽略，等待后续工具更新解决语法冲突问题。

通过以上方法，开发者可以顺利构建 Swift-Book 项目，并理解其中涉及的技术细节和潜在问题。