errors.md

错误参考

本文档按“查表”方式列出 Dolang 常见错误与处理建议。

错误类别

类别	何时出现	能否被 $catch 捕获
词法错误	代码还没被正确切 token	不能
语法错误	parser 无法构造合法语句	不能
运行时错误	程序执行过程中失败	通常可以
项目装载错误	入口、模块、项目加载失败	不建议把它当普通业务错误处理

常见运行时错误

类型不匹配

$ x: Int = "hello";

说明：声明类型和实际值不一致。

未定义变量

$>> missing;

说明：变量未声明就被读取。

除零

$>> 10 / 0;

说明：普通运行时错误，可用 $try / $catch 包住。

文件读取失败

$mod std.fs;
$try {
    $ content = fs.read_text("missing.txt");
} $catch err {
    $>> err;
}

说明：文件不存在、路径错误或把目录当文件读取时都可能触发。

模块加载失败

$mod missing.module;

说明：通常发生在装载阶段，优先先修模块路径和项目结构，而不是把它当正常业务分支。

$catch 可捕获性速查

场景	是否建议写成“可捕获”
$throw "oops"	是
除零	是
未定义变量	是
类型不匹配	是
文件读取失败	是
模块加载失败	谨慎，不作为主线业务流程依赖
语法错误	否

err 怎么用

主线安全用法：

• 直接打印 err
• 拼接到日志字符串
• 返回默认值或改写 HTTP 响应

不把 err 当固定字段结构来写文档承诺。

排查建议

1. 先看错误类别
2. 再看报错位置
3. 缩成最小 .dol 文件
4. HTTP 问题优先用 dolang test --route ...

交叉阅读

• 主线说明：../guide/10-error-handling.md
• 常见错误附录：../guide/appendix/common-errors.md