莱昂哈特庄园Leonhart Manor

Nav2 的参数写错了,往往要等启动后才在日志里看到一条难懂的报错,或者干脆被悄悄忽略。我写了一个不依赖 ROS 的静态检查工具,几毫秒就能指出出错的那一行。

写 nav2_params.yaml 很容易出错:类型填岔了,启动后日志里只甩出一条让人摸不着头脑的异常;插件名拼错了,节点起不来;参数名写错了更麻烦,程序不报错,直接把那条配置悄悄吞掉。每次改完都得重新拉起整套导航栈才能发现,太耽误时间。

nav2lint 就是用来在启动前把这些低级毛病先揪出来的。

能做什么

它能检查参数类型、插件列表和参数名,报错直接指到行号,支持 Humble、Jazzy、Kilted 和 Rolling,也会自己判断这份配置是写给哪个发行版的:

  • 迁版本之前可以先检查一遍,比如拿一份 Humble 的配置去跑 Jazzy 规则,看会报哪几处;
  • 确定怎么改的问题能用 --fix 直接修,想先预览改动就加 --diff;
  • --watch 会在保存文件时自动重查,--format json 方便接进 CI;
  • --explain 用来看某条规则的说明,--describe 可以查某个参数的类型、默认值和出处;
  • 另外顺手带了个 VS Code 集成。

它只依赖 PyYAML,不用装 ROS,也不会真去起 Nav2,所以 Windows、Linux 和 WSL 下都能跑:

pip install -e .
nav2lint --distro humble nav2_params.yaml
nav2lint --distro jazzy old_humble.yaml   # 迁移前检查

现状

11 月 1 日开始写,2 日夜里到 3 日凌晨连推了 v0.2.0 到 v0.3.1,3 日白天又补齐了中文 README、五分钟上手教程和一段终端演示动图,第一阶段到这里就算收尾了。现在转入维护状态,有能复现的 bug 或误报我会改,新功能等有明确需求再加。

静态检查没法替代实际运行,有些问题得等 Nav2 真正跑起来才会暴露;不过能在启动前先少踩几次坑就够了。

封缄于 2026 年 11 月 2 日