参数声明：配置契约，而不是静默默认

1. 「改了没效果」往往是契约缺失

膨胀半径「改了没效果」——yaml 写着 inflation_radius，节点实际读的是 costmap.inflation_radius，未声明访问又静默落到默认。RViz 一切如旧，调参的人开始怀疑导航。根因不是 Nav2，是参数没有契约：键名、类型、默认、是否动态，全靠口头传统。

未声明参数让演示永远成功，也让产品配置永远不可审计。declare_parameter 把名字、类型、默认和描述固定下来；校验失败应在启动时阻断，而不是带着错配置跑出门。

2. 声明要覆盖什么

一次合格的声明至少有：类型、默认值、给人看的描述、若可动态修改则写清范围与副作用。描述写「改了会发生什么」，例如：「膨胀半径（米）。运行时修改会触发代价地图清理。」比「膨胀参数」有用。

命名要分层，避免十个裸 rate。静态参数（仅 configure 读）与动态参数分开：active 后半生效是「有时有效」的温床。

cpp

this->declare_parameter<double>(
  "inflation_radius",
  0.55,
  rcl_interfaces::msg::ParameterDescriptor{}
    .set__description("膨胀半径（米）。动态修改会触发相关清理。"));

3. 动态参数：副作用是契约的一部分

可运行时修改的参数必须回答：是否立即生效、是否清空地图/重置滤波、运动中是否允许改、非法值如何拒绝。参数回调也占执行器——里面做巨型重建，会像堵服务回调一样拖死控制。重活进工作队列，回调只设旗标。

与 lifecycle 交点：仅 configure 可读的参数，不要在 active 偷偷生效一半；需要重启才完整生效的，描述里写明，必要时拒绝 active 期修改。

4. yaml、覆盖顺序与漂移

团队必须固定覆盖顺序（通常：命令行 > launch 传入 > yaml > 代码默认），并在启动摘要打印关键有效值。Composable 容器里覆盖更绕，以加载后的 ros2 param get 为准。

CI 应检查：yaml 键 ⊆ 已声明键；删除代码参数同步删 yaml。未声明访问统计当质量债，清零前不要谈「灵性调参」。

5. 安全参数与车队灰度

限速、膨胀、急停超时、碰撞阈值：变更走评审与实验袋，不是个人下午手感。车队热更新要灰度（一台 → 小批 → 全量），并保留配置包版本回滚。只回滚代码不回滚 yaml（或相反），会出现「已回滚却依旧」的幻觉——发布物应捆绑代码版本与配置版本。

身份类参数（轮半径、设备号）宜从硬件清单生成 overlay；人手主要改策略类参数。远程配置中心推送后，节点侧仍须过声明校验——节点是最后防线。

6. 模式配方，而不是一次拧二十个键

「窄道模式」应是一次模式切换，内部套参数快照；让操作员逐个拧膨胀与限速，既慢又危险。参数提供旋钮，模式管理提供场景配方。字典里用联动组标注（速度/加速度/膨胀/足迹），改一处提示其它成员，CI 可跑不变量。

7. 验收

错误键名或类型：启动失败，日志写明键、期望类型、来源文件。
动态合法值：副作用与描述一致；非法值拒绝并说明原因。
故意未声明访问：统计能抓住，最终应清零。
安全参数变更：有审计（谁/何时/旧新值）。
真机/仿真 overlay：启动摘要能指认加载了哪一套。

参数是行为接口。声明把它拉进阳光，描述与副作用让现场可操作，版本与灰度让回滚可指认。配置不可审计时，再精致的控制器也只是在噪声上作画。

8. 案例：演示默认绑架产品速度

演示为求「总能起」，代码默认把最大速度设得很低。产品 yaml 想提速，但某节点未声明对应参数，一直吃演示默认——客户抱怨「还是慢」。上线未声明访问统计并清零后，速度才按 yaml 生效。默认可以保守，但必须能被 ros2 param describe 看见；看不见的保守是陷阱。

9. 与录包复盘

导航事故袋若没有参数快照，只能猜当时膨胀与限速。状态层录包应包含关键参数 dump（或安全参数白名单）。证据链完整，才分得清是算法责任还是配置责任。