错误诊断与调试

本章导读

调试能力 = 诊断阅读能力 × 定位方法论。本章先解决"读"：xlang 的每条诊断都带位置（file:line:col）、阶段标签（[parse]/[sem]）和消息，--json 把它们变成机器可读的三字段结构；运行时错误则要认三种形态——会说话的异常（uncaught XxxError: 消息）、沉默的 fatal（exit 3/4 一个字符都不打）、和根本不像语言错误的进程级死亡（exit 127）。再解决"找"：编译期问题用第 37 章的管线取证法（check 定阶段、ir 看语义、--dump-dir 拿六件套），运行期问题用最小复现、二分注释、防御性断言三板斧。本章不写调试器——dbg/dap 已从正式 CLI 删除（39.10 如实说明官方口径与替代方案）。读完后建议把 39.6 的三形态对照表和深入细节 3 的退出码全景表打印出来贴在手边，它们是你在 xlang 世界里的急诊分诊台。

39.1 四层防线总览

一个 xlang 程序从出生到运行要过四道关，每一关的错误形态、诊断能力、排查工具完全不同——先建立全景，再逐层深入：

关键认知：越往下层，诊断越少，预防越重要。①层有精确到列的诊断和错误恢复；②层有符号名可查；③层一半会说话一半沉默；④层只剩一个退出码。高手的工作流是把问题尽量堵在上层——类型标注让 sem 替你把关（①），assert 在状态变坏的第一现场报警（③），防御性检查让 fatal 无机可乘（③④）。

39.2 诊断格式与 --json

编译期诊断的统一格式四段式：文件:行:列: [阶段] 消息——

e_sem.xl:2:13: [sem] 初始化表达式类型和声明类型不匹配: target int, value string
e_sem.xl:3:13: [sem] undeclared identifier 'm'

消息文本中英文混合是当前现实（初始化错误用中文，undeclared identifier 用英文）——写工具匹配诊断时请按结构（位置+阶段）解析，别按消息文本匹配。

xl check --json 把诊断结构化，三个顶层字段（实测三种结果）：

$ xl check app.xl --json
{"ok":true,"phase":"checked","diagnostics":[]}
$ xl check e_parse.xl --json
{"ok":false,"phase":"parse","diagnostics":[{"file":"e_parse.xl","line":4,"column":4,"message":"语法错误"}]}
$ xl check e_sem.xl --json
{"ok":false,"phase":"sem","diagnostics":[{"file":"e_sem.xl","line":2,"column":13,"message":"初始化表达式类型和声明类型不匹配: target int, value string"},{"file":"e_sem.xl","line":3,"column":13,"message":"undeclared identifier 'm'"}]}

phase 是机器分诊的核心字段，实测三态：checked（全部通过）、parse（语法阶段倒下）、sem（语义阶段倒下）。注意词法层的错误也归在 parse 阶段——39.3 会看到这个归并的原因。diagnostics 数组的元素永远带 file/line/column/message 四字段，编辑器插件据此画波浪线即可，不需要理解消息内容。

39.3 lex/parse：报一次停

先看一个反直觉实测：@ 这种"非法字符"在 xlang 里根本不触发词法错误——

$ cat e_lex.xl
func main(...)
    int n = 10 @ 5
end
$ xl lex e_lex.xl
   ……
   2:13  INT              10
   2:16  AT               @        ← @ 被切成合法 AT token
   2:18  INT              5
   ……
# exit 0 —— lex 阶段毫无意见
$ xl check e_lex.xl
e_lex.xl:2:16: [parse] 语法错误   ← 是 parse 不认 AT

xlang 的 lexer 对单字符几乎来者不拒（@、$ 都有 token 名），真正的词法错误只剩少数形态——最典型是未闭合的字符串，它产生专门的 ERROR token：

$ xl lex e_str.xl
   ……
   2:16  ERROR            "unclosed  # 未闭合的字符串
   ……
cannot dump tokens: e_str.xl
# exit 1 —— token 流照打，收尾报错
$ xl check e_str.xl
e_str.xl:2:16: [parse] 未闭合的字符串

所以 phase 字段没有 "lex" 值的原因就清楚了：词法问题要么不存在（被切成合法 token，留给 parse 拒），要么以 ERROR token 形式进入 parse 被拒——诊断上统一记 parse 阶段。

parse 的脾气是"报一次就停"。语法树断了就续不上，继续分析只会产生垃圾诊断，所以 parse 永远只报第一条（上面 JSON 样本里 diagnostics 只有一项）。推论：修 parse 错误永远从报出来的第一条修起，修完重跑——后面的"错误"很可能只是第一条的连锁反应。

39.4 sem：收集多个错误

语义阶段相反——它走遍整棵树，把能收集的错误一次性报完（实测一个 4 行错误的文件报出 5 条）：

$ cat e_multi.xl
func main(...)
    int a = "x"
    int b = "y"
    foo()
    int c = a + "z"
end
$ xl check e_multi.xl
e_multi.xl:2:13: [sem] 初始化表达式类型和声明类型不匹配: target int, value string
e_multi.xl:3:13: [sem] 初始化表达式类型和声明类型不匹配: target int, value string
e_multi.xl:4:5: [sem] undeclared identifier 'foo'
e_multi.xl:5:15: [sem] 字符串拼接两侧都必须是 string
e_multi.xl:5:15: [sem] 初始化表达式类型和声明类型不匹配: target int, value string

看第 5 行：一个 a + "z" 触发两条诊断——先报"拼接两侧必须都是 string"，随后报"初始化类型不匹配"。第二条是第一条的级联：拼接失败后结果类型无法确定，按 int 继续检查自然又不匹配。由此得到本章最重要的修复纪律：级联诊断，先修第一条。5 条诊断的真实问题只有 4 个，修完第 5 行的拼接类型，第二条初始化不匹配自动消失。一堆报错扑面而来时别慌——按行号排序从第一条修，每修一条重跑 check，诊断数量常常应声减半。

sem 还是编译期防线的最后一道闸，很多"运行时灾难"在这里就被拦下——实测把 null 直接赋给 string：

r_null.xl:2:16: [sem] 初始化表达式类型和声明类型不匹配: target string, value null

这类错误根本活不到运行期。类型标注写得越认真，sem 替你拦截的就越多——这就是第 4 章"建议显式标注类型"的深层回报。

39.5 check 与 CI 集成

xl check 是为自动化而生的命令：不运行、不生成、只诊断。它与 CI 的契约就三条（均实测）：

一个最小但够用的 CI 流水线片段：

for f in src/*.xl; do
    xl check "$f" --json > "reports/$(basename $f .xl).json" || FAILED=1
done
[ -n "$FAILED" ] && exit 1

每个文件一份 JSON 诊断存档，phase 字段还能做精细策略：比如 parse 失败算阻塞（代码根本写错了），sem 里某些已知历史问题可以暂时豁免——机器可读的意义就是策略可编程。嵌入场景同样能力在 xlcCheck（第 38 章 38.10），IDE 保存即检查走那条路。

39.6 运行期三形态对照

编译通过后，错误的画风突变——先认全三种形态（全部本章实测）：

形态一：会说话的异常（exit 1）。throw、除零、断言失败这类可捕获错误，没人 catch 时运行时在 stderr 打一行 uncaught 诊断：

$ xl run r_throw.xl
before throw
tcc: __xlvfs__/module.c:449: warning: 'return' with no value
3:5: uncaught Error: boom happened
# exit 1
$ xl run r_divzero.xl
before
5:22: uncaught ZeroDivisionError: integer division by zero
$ xl run r_assert.xl
3:5: uncaught AssertionError: n should be 42

三个细节：行:列: 前缀不带文件名（多文件工程里要结合上下文判断）；uncaught 时 TCC 会附带一条 warning: 'return' with no value 噪音（深入细节 2 解释，可忽略）；诊断全在 stderr，程序自身输出在 stdout，2>nul 可以只看正常输出。try/catch 接住则完全无害（caught: boom happened / recovered，exit 0）。

形态二：沉默的 fatal（exit 3 / 4）。数组越界、as 失败、null 调方法——程序逻辑已错的信号，运行时选择立即终止，一个字符的诊断都不打：

$ xl run r_oob.xl       # arr[10]，数组只有 3 个元素
before
# exit 3 —— "after" 永远没机会打印，也没有任何错误消息
$ xl run r_asfail.xl    # Animal 实例 as Dog
before
# exit 4 —— 同样沉默
$ xl run r_nullcall.xl  # Point p = null 然后 p.move(1)
before
# exit 4 —— null 调用与 as 失败同码

try 兜不住它们（第 10 章已定论，本章复核）：try/catch 包越界，catch 块根本不执行，照样 exit 3。排查手段只能靠 39.9 的方法论（println 二分 + assert 前移）。

形态三：进程级死亡（exit 127）。程序根本没好好跑起来或中途崩溃，至少四种成因（全部实测过）：

127 的排查心法：它从不是 xlang 语言层的错误——别去查语法，先按上表对号成因。三形态合起来的分诊口诀：有消息看消息（形态一），没消息看退出码（3/4 查 fatal 点，127 查进程环境）。

39.7 异常定位与无栈现实

uncaught 诊断的行号是 throw 点，不是出错逻辑的发源地——实测三层调用链：

$ cat r_prop.xl
func inner()
    throw "deep error"
end
func outer()
    inner()
end
func main(...)
    outer()
end
$ xl run r_prop.xl
2:5: uncaught Error: deep error
# 报的是第 2 行 inner 里的 throw，没有 outer/main 的调用链

当前版本没有调用栈输出——throw 穿过 outer、main 的轨迹被吃掉了。小项目无所谓，大项目里一个底层工具函数被几十处调用时，"谁把坏数据传进来的"才是你真正要问的。三种补偿手段：

手段一，分段 catch 补上下文。在关键中层函数 catch 后重新 throw 带上下文的分类错误（第 10 章重抛模式）：底层报"deep error"，中层包装成 throw FileError "loadConfig: deep error"——消息链代替调用栈。

手段二，日志打点。log 模块（第 36 章）在中层入口打 info 级"进入 outer, 参数=..."，uncaught 后按日志回溯路径——比反复改代码加 println 体面。

手段三，防御性断言前移。在函数入口 assert 参数不变量（39.9 展开），让错误在最近现场爆炸——断言消息里写明期望与实际，比 uncaught 的裸行号信息量大得多。

39.8 管线取证调试法

怀疑"编译器理解错了我的代码"或错误发生在链接期时，启用第 37 章建立的取证工具链。系统化后的排查动线：

① xl check --json        → phase 字段直接告诉你是 parse 还是 sem 的问题
② xl parse f.xl          → 语法树长什么样？优先级、结构是否符合预期
③ xl ir f.xl             → 语义加工后什么样？隐式转换、注入物是否如预期
④ xl cgen f.xl --dump-dir dump   → 六件套全量取证（tokens/ast/xlir/abi/c/h）
⑤ xl run f.xl --save-temps       → 拿到正在被执行的那份 module.c 原文

链接期错误是这套工具的主战场。第 37 章的 unresolved reference 案例完整走一遍动线：tcc: tcc: error: unresolved reference to 'c_add3'——报错来自 TCC（②层），说明 xlang 侧全部通过；报错里的符号名 c_add3 是你 extern 声明的名字；cgen --emit 看生成 C 里这个符号的声明形态对不对；最后确认 --loadlib/--link 是否给了符号的"尸体"。报错路径里的 __xlvfs__/ 前缀（如 csrc_0.c）提醒你：这份 C 是动态 VFS 里的生成物，不是磁盘文件，要看原文请 --save-temps 导出。

ABI 位宽冲突同样靠 cgen 取证：第 37 章的 incompatible types for redefinition（xlang int 64 位 vs C int 32 位）在生成 C 里一眼可见——声明是 long long helper_triple_plus1(long long)，定义是 int helper_triple_plus1(int)，对不上就是位宽写错（int32 修正）。凡是"编译过了但链接炸"的问题，答案都写在生成 C 里。

39.9 实用调试技巧

技巧一：最小复现。遇到诡异行为，先把程序砍到不能再砍——本书第 29 章定位 Queue<var> 段错误、本章定位多线程 string() 空串，用的都是这个套路：原程序几百行 → 砍掉无关功能 → 砍掉一半代码看问题是否还在 → 最终得到一个十几行、任何人拿去都能复现的文件。最小复现既是报 bug 的礼仪，也是最快的定位器——问题往往就在砍掉某一块的瞬间自己现形。

技巧二：二分注释法。fatal 静默死亡（exit 3/4）没有行号时，用注释做二分查找：把 main 后半段整段注释掉，程序不崩了，说明 fatal 在后半段；恢复一半再试，几次二分即可锁定到行。配合 println 打点更精确：

func main(...)
    println("checkpoint A")     // 打出来了吗？
    stepOne()
    println("checkpoint B")     // 到这就断了 → fatal 在 stepOne
    stepTwo()
    println("checkpoint C")
end

最后一个打印出来的 checkpoint 与下一个之间的代码就是案发区间。exit 3 查数组/容器下标，exit 4 查 as 转换与可能为 null 的对象——按码索骥比逐行读快得多。

技巧三：防御性断言。把"这里应该成立"的每一个假设写成 assert，错误就会在第一现场爆炸而不是污染到下游：

func average(array<int> xs) as float
    assert xs.length > 0, "average: empty array"
    int total = 0
    for x in xs
        total += x
    end
    return total / float(xs.length)
end

assert 失败是可捕获、带消息、带你写的现场描述的 AssertionError（exit 1）——比越界静默 exit 3 友好一百倍。入口断言参数、循环断言不变量、返回前断言结果范围，断言密度就是你的调试安全网密度。

技巧四：println 打点的两个现代注意。一，多线程/嵌入宿主场景别用 string() 显式转换做打点（第 38 章实测它返回空串），用 println 多参直打 println("v =", v)；二，打点输出量大时 xl run app.xl 2>nul 可以临时屏蔽 uncaught 的 TCC 噪音只留 stdout。

39.10 调试器现状

必须如实相告：当前版本没有断点调试器。docs/命令行设计.md §6 的官方口径（原文照录）："首个发布版本不提供 dbg、dap 或独立 xldbg.exe。此前的 probe 与 DAP smoke 不能执行真实断点控制，也不能提供真实栈帧和变量，因此已从正式 CLI 删除，不能作为兼容命令或隐藏回退重新进入。"

删除而不是留个半成品，是对调试工具的基本要求——一个不能真正暂停、看栈、读变量的"调试器"比没有更害人。官方对回归的条件同样明确：调试器必须完成真实被调试进程、暂停/恢复、调用栈、作用域、变量快照和 DAP 映射后才可重新设计公开命令，且不得进入 xl.dll 运行版。

所以本章前九节就是你的"当前调试器全家桶"：check --json 是静态分析器，管线取证是透视仪，assert 是断点，println/log 是手表，最小复现与二分法是手术刀。它们组合起来覆盖了断点调试器九成以上的日常用途。等官方调试器落地，这一章教的诊断分类与定位方法论依然是基本功——调试器只是让同样的认知有了更快的交互。

深入细节

⚠️ 常见错误

e_lex.xl:2:16: [parse] 语法错误

e_multi.xl:5:15: [sem] 字符串拼接两侧都必须是 string
e_multi.xl:5:15: [sem] 初始化表达式类型和声明类型不匹配: target int, value string

try
    println(string(arr[10]))
catch e
    println("caught")   // 永远不会执行
end
# exit 3 —— 静默

$ xl run app.xl
# 静默，exit 127

    println("v = " + string(v))   // 多线程宿主下输出 "v = "（空串）

本章小结

复习题

1. 四层防线各层的典型错误与诊断形态分别是什么？为什么越往下层越要靠预防？
2. --json 诊断的 phase 字段有哪三个实测值？词法错误归在哪个阶段，为什么？
3. parse 与 sem 的错误报告策略有何不同？面对 5 条 sem 诊断应该按什么顺序修，为什么？
4. exit 1、3、4、127 各自对应什么错误形态？try/catch 能兜住哪些？
5. uncaught 诊断的行号指向哪里、缺什么信息？写出三种补偿手段。当前版本为什么没有调试器？

编程练习