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 日