指向错误：uutils coreutils 中的编译器风格诊断信息
uutils 团队在官方博客上发表文章，介绍了他们在 coreutils 中引入编译器风格诊断信息的工作。文章指出，50 年来，Coreutils 一直在不断演进。现在，他们通过重新思考错误报告方式，将这一创新推向了新的高度。传统的 Unix 工具将错误报告为 stderr 上的一行文本，只说明出了什么问题，而不说明在哪里。对于大多数命令来说，这已经足够了，但对于更复杂的工具，编译器风格的诊断信息可以提供更好的用户体验。
背景：Unix 工具的错误报告传统
传统的错误报告方式
自 Unix 诞生以来，命令行工具的错误报告方式几乎没有变化：
$ ls /nonexistent
ls: cannot access '/nonexistent': No such file or directory
这种错误报告的特点：
- 单行文本，输出到 stderr
- 格式：
工具名: 错误描述 - 只说明出了什么问题，不说明在哪里
- 没有上下文信息
- 没有修复建议
为什么传统方式成为标准
这种简单的错误报告方式之所以成为标准，有几个原因：
- 历史原因：早期的终端功能有限，只能显示文本
- Unix 哲学：做一件事并做好，错误报告保持简单
- 管道兼容性：单行错误信息不会干扰管道和脚本
- 实现简单：开发者不需要实现复杂的错误报告逻辑
传统方式的局限
然而，随着工具变得越来越复杂，传统的错误报告方式暴露出了局限：
- 缺乏上下文：用户不知道错误发生在输入的哪个位置
- 难以调试：对于复杂的输入（如多行文本、配置文件），用户难以定位问题
- 没有修复建议：用户需要自己猜测如何修复问题
- 不一致性：不同工具的错误格式和详细程度不一致
- 对新手不友好：新手用户可能不理解错误信息的含义
编译器风格的诊断信息
什么是编译器风格的诊断信息
编译器（如 GCC、Clang、Rustc）长期以来一直使用更复杂的诊断信息：
error: expected `;` after expression
--> src/main.rs:2:18
|
2 | let x = 5
| ^ expected `;`
|
= help: add `;` here
这种诊断信息的特点：
- 错误类型（error/warning/note/help）
- 错误位置（文件名:行号:列号）
- 源代码上下文（显示出错的代码行）
- 错误指向（用
^指向具体的出错位置） - 修复建议（help 信息）
编译器风格诊断的优势
- 精确定位：用户可以立即知道错误发生在输入的哪个位置
- 上下文理解：源代码上下文帮助用户理解错误的背景
- 可操作性：修复建议让用户知道如何解决问题
- 一致性：统一的格式让用户更容易理解和处理
- 新手友好：详细的信息帮助新手理解和学习
uutils coreutils 的实现
为什么在 coreutils 中引入编译器风格诊断
uutils 是用 Rust 重写的 GNU coreutils 的替代品。团队决定在 coreutils 中引入编译器风格的诊断信息，原因如下：
- Rust 生态的影响：Rust 编译器（rustc）以其优秀的诊断信息著称，uutils 团队希望将这种体验带给 coreutils 用户
- 复杂工具的需求：一些 coreutils 工具（如
sort、awk、sed）处理复杂的输入，传统的错误报告不够用 - 用户体验改进：更好的错误报告可以显著提升用户体验，减少调试时间
- 教育价值：详细的诊断信息可以帮助用户学习命令行工具的使用
实现架构
uutils 团队设计了一个统一的诊断框架，用于在所有 coreutils 工具中生成编译器风格的诊断信息。
核心组件
诊断类型：
Error：错误，导致命令失败Warning：警告，不影响命令执行但需要注意Note：附加信息，提供额外的上下文Help：帮助信息，提供修复建议
位置信息：
- 文件名
- 行号
- 列号
- 字节偏移（对于二进制文件）
源代码上下文：
- 显示出错的行
- 支持多行上下文
- 行号显示
错误指向：
- 用
^指向具体位置 - 支持范围指向（
^^^） - 支持多位置指向
- 用
示例
以 cut 命令为例，传统的错误报告：
$ echo "a,b,c" | cut -d , -f 4
# 没有输出，因为第4个字段不存在
编译器风格的诊断：
$ echo "a,b,c" | cut -d , -f 4
warning: field 4 does not exist in input
--> <stdin>:1:5
|
1 | a,b,c
| ^ only 3 fields available
|
= note: use -f 1-3 to select all available fields
再以 sort 命令为例，当输入格式不符合预期时：
$ sort -k 2,2n input.txt
error: invalid numeric value at field 2
--> input.txt:3:10
|
3 | 1 abc 3
| ^^^ expected numeric value
|
= help: remove -n flag or ensure field 2 contains only numbers
技术实现细节
使用 Rust 的生态系统
uutils 利用了 Rust 生态中的相关库：
annotate-snippets：一个 Rust 库，用于生成编译器风格的诊断信息输出。它提供了灵活的 API，可以自定义诊断的各个方面。
miette：另一个流行的 Rust 错误处理库，提供了丰富的诊断信息功能。虽然 uutils 最终选择了 annotate-snippets，但 miette 的设计也提供了参考。
自定义解析器：对于需要解析输入的工具（如
sort、awk），uutils 实现了自定义的解析器，能够记录每个 token 的位置信息，用于错误报告。
位置追踪
实现编译器风格诊断的关键是位置追踪。uutils 团队在以下层面实现了位置追踪：
- 输入读取层：在读取输入时记录每个字符的位置（行号、列号）
- 解析层：在解析输入时，将位置信息与每个语法元素关联
- 错误处理层：在生成错误时，将位置信息传递给诊断框架
- 输出层：诊断框架根据位置信息生成带上下文的输出
兼容性考虑
引入编译器风格诊断需要考虑向后兼容性：
- 环境变量控制：通过环境变量（如
UUTILS_DIAGNOSTICS=classic）允许用户切换回传统的错误报告方式 - 管道模式：当输出不是终端（如管道到文件或其他命令）时，自动简化诊断信息，避免干扰管道处理
- POSIX 合规：确保在 POSIX 模式下，错误信息的格式符合 POSIX 标准
- 渐进式引入：先在少数工具中引入，收集反馈后再推广到所有工具
对命令行工具设计的启示
uutils 的这项工作对命令行工具的设计有以下启示：
1. 错误报告是用户体验的重要组成部分
很多开发者在设计命令行工具时，只关注功能实现，而忽视了错误报告。但实际上，用户在使用工具时，遇到错误是常态而非例外。好的错误报告可以显著提升用户体验，减少用户的挫败感和调试时间。
2. 借鉴其他领域的优秀实践
编译器领域在错误报告方面积累了几十年的经验，其他类型的工具可以借鉴这些实践。uutils 的工作展示了，即使是传统的 Unix 工具，也可以从编译器的错误报告方式中受益。
3. 渐进式改进
不需要一次性重写所有工具的错误报告。可以先在少数复杂工具中引入新的诊断方式，收集用户反馈，验证效果，然后再逐步推广。这种渐进式的改进方式风险更小，也更容易获得用户的接受。
4. 保持兼容性
在引入新特性时，必须考虑向后兼容性。提供环境变量开关、自动检测输出类型、保持 POSIX 合规等措施，可以确保新特性不会破坏现有的工作流。
5. 利用现代编程语言的优势
Rust 等现代编程语言提供了更好的错误处理和类型系统，使得实现复杂的诊断信息更加容易。uutils 选择用 Rust 重写 coreutils，不仅是为了性能和安全，也是为了利用 Rust 生态中的优秀库来改进用户体验。
总结
uutils coreutils 引入编译器风格诊断信息的工作，代表了命令行工具错误报告方式的一次重要演进。
核心要点：
- 传统方式的局限：Unix 工具传统的单行错误报告只说明出了什么问题，不说明在哪里，对于复杂工具不够用
- 编译器风格的优势：精确定位、上下文理解、可操作性、一致性、新手友好
- uutils 的实现：统一的诊断框架、位置追踪、利用 Rust 生态、兼容性考虑
- 设计启示：错误报告是用户体验的重要组成部分、借鉴其他领域的优秀实践、渐进式改进、保持兼容性、利用现代编程语言的优势
这项工作提醒我们，即使是最基础、最传统的工具，也有改进和创新的空间。50 年来，Coreutils 一直在不断演进，而编译器风格的诊断信息是这一演进历程中的最新一步。未来，我们可以期待更多命令行工具采用更好的错误报告方式，为用户提供更好的体验。
正如文章标题所说，"指向错误"不仅仅是技术上的改进，更是一种设计理念的转变：从"告诉用户出了什么问题"到"帮助用户理解和解决问题"。这种理念的转变，将让命令行工具变得更加友好、更加易用。
原文链接：https://uutils.org/blog/2026-08-error-diagnostics/