NavMeshAgent跳跃失效：原因、解决路线与混合控制器实战

上周有个做独立游戏的朋友把一段跳跃代码发过来说角色“跳不起来”。我扫了一眼Input.GetKeyDown判断没问题AddForce和transform.Translate两种写法他都试过落地动画也切了唯独角色纹丝不动。把日志打出来一看真相很朴素——Update 里 y 从 0 涨到 0.8LateUpdate 里又老老实实回到 0。这不是跳跃失败是有人在后面把它按了回去。这个场景在用了 NavMeshAgent 的项目里出现频率高得离谱寻路跑得好好的一加跳跃就废或者站着能跳、一按方向键就跳不起来再或者跳起来了人在半空被一根看不见的绳子拽回地面。绝大多数人第一反应是去改跳跃代码改到最后把整个移动脚本重写了一遍问题还在。根子不在跳跃那一行在于 NavMeshAgent 这个组件从一开始就没打算让你在垂直方向上动。它是个平面搬运工你让它干活它就把 transform 的 y 也一并管了。这篇东西就是把这个“管”字拆开讲它在什么时候写、写到什么程度、哪几个开关能松开以及松开之后会连着冒出哪些新坑。适合已经在项目里用 NavMeshAgent 做寻路、现在要给角色加跳跃或者位移技能的人看也适合刚接触 Unity 导航系统、被“为什么我的角色飘不起来”卡了半天的同学。代码会给到能直接跑的程度但更重要的是每一步为什么这么写。1. 跳跃代码“写了等于没写”先把症状拆开看1.1 三种典型症状对应三种完全不同的病因同样是“跳不起来”背后的机制其实分三类如果你不先分清是哪一类后面的修改基本就是碰运气。我在排查这类问题时习惯先让对方描述现象因为现象本身就能把范围缩小一大半。第一类是静止能跳、一动就跳不起来。这个最容易被误判成“移动状态锁定了跳跃”。真实原因通常简单粗暴Agent 只有在有路径、有位移意图的时候才会每帧把 transform 往路径上拉。你站着不动它写回的值和当前值一模一样看不出任何异常你一走动它每帧都在把 transform 拽向 NavMesh 上的下一个点y 自然被抹平。很多人还会因为“站着能跳”而误以为代码逻辑是对的转而去怀疑输入系统或者动画状态机白白浪费半天。第二类是跳起来了但在空中被拽回地面观感像脚上拴了根橡皮筋。这类多半是 Agent 的updatePosition还开着它的采样高度就是脚下 NavMesh 的表面高度你往上加多少它下一帧就还回来多少。表现上往往还有一点上升段看着还行下落段特别“急”因为上升是你加的位移和它的修正互相抵消下落是两边方向一致。第三类是跳跃瞬间抽搐、闪回落地后彻底不动了。这一类基本可以确定是 Rigidbody 和 NavMeshAgent 挂在同一个物体上两个系统抢着写 transform物理积分写一次、Agent 对齐一次画面就抖。更麻烦的是落地后 Agent 可能已经掉出 NavMesh之后所有SetDestination调用都会报错角色变成一根木头。症状表面现象真实原因最快的验证方式A站定能跳移动中跳不起来Agent 有路径时每帧回写 transformy 被对齐移动中把agent.enabled临时关掉再试B起跳后迅速被拉回地面updatePosition truey 采样 NavMesh 高度把updatePosition设为 false 再试C抖动、闪回、落地后失能Rigidbody 与 Agent 双写 transformAgent 掉出网格看 Console 有没有isOnNavMesh相关报错1.2 打一行日志锁定到底是谁在改 transform在动手改架构之前我强烈建议先花三分钟做一次“取证”。方法很简单在 Update 和 LateUpdate 各打一条日志把transform.position.y和agent.nextPosition.y同时打出来然后按下跳跃键。using UnityEngine; using UnityEngine.AI; public class AgentPosProbe : MonoBehaviour { NavMeshAgent agent; void Awake() { agent GetComponentNavMeshAgent(); } void Update() { if (Input.GetKeyDown(KeyCode.J)) transform.position Vector3.up * 1.5f; Debug.Log($U f{Time.frameCount} t{transform.position.y:F3} n{agent.nextPosition.y:F3}); } void LateUpdate() { Debug.Log($LU f{Time.frameCount} t{transform.position.y:F3} n{agent.nextPosition.y:F3}); } }判读方式很直接如果 Update 那一行 y 是 1.5LateUpdate 那一行 y 回到 0而n始终在地面高度——那就是 Agent 在 Update 之后、LateUpdate 之前把位置改回去了问题定性完成剩下的全是方案选择。如果两条日志的 y 都是 1.5但画面里角色没动那说明改的不是你以为的那个物体检查一下脚本挂在了父节点还是子节点上模型是不是在另一个层级。还有一个不要钱的土办法在 Scene 视图里选中角色NavMeshAgent 会画出一个圆柱或者球形的 Gizmo。按下跳跃键的时候盯着这个 Gizmo 看。如果 Gizmo 一动不动、只有模型往上飘说明视觉和逻辑已经脱节如果 Gizmo 跟着上去又瞬间掉下来那就是被回写了。这个方法比读日志直观适合快速确认。提示我在几个 Unity LTS 版本上反复验证过Agent 的位置写入发生在所有 MonoBehaviour 的 Update 之后、LateUpdate 之前。不同版本可能有细微差别但用上面这两行日志一秒就能确认不要凭记忆猜。2. NavMeshAgent 的职责边界它只是个平面搬运工2.1 路径点看着是 Vector3实际只有 x/z 有意义NavMesh 本质上是一堆凸多边形的集合烘焙的时候把场景里的可行走表面切成片运行时 A* 在这些多边形上找一条折线。这条折线的每个拐点在代码里是Vector3但它的 y 值不是“你想去哪一层”而是“这个点在网格表面上有多高”。换句话说Agent 的移动模型里根本没有“离开表面”这个概念。这一点想通了很多现象就不用解释了。你给它一个空中的目标点它会先SamplePosition把点投影到最近的网格表面然后沿着表面走过去。你在半空中给它设目标它会把你拉回地面再走。你给它一个高台上的点如果那个高台没烘焙进同一块 NavMesh它会直接判定不可达。Agent 唯一能表达高度的参数是baseOffset。它的语义是“把物体的 transform 沿 up 方向抬离 NavMesh 表面多少”听起来像跳跃实际上更像给不同体型的角色对齐脚底——比如你的模型原点在腰部而不是脚底就得靠这个值把视觉拉下来。2.2 一帧之内谁先写谁后写理解执行顺序是解决这类问题的关键。我把它整理成一张表方便你对照自己项目里各个系统的位置阶段正在发生什么对 y 的影响Update读输入、算速度、SetDestination你在这里加的高度是本帧有效的Agent 内部更新沿路径把 transform 拉向下一个拐点y 对齐网格你加的高度在这里被抹平LateUpdate相机跟随、IK、朝向修正这里改位置下一帧照样被抹FixedUpdateRigidbody 积分、碰撞求解与 Agent 的回写互相打架表格里最容易被忽略的是最后一行。物理积分走的是固定步长一帧里可能跑零次也可能跑好几次而 Agent 的回写是每帧一次。两个频率不同的系统同时写同一个 transform结果就是你在编辑器里看到的“抖动”和“偶发穿模”。这类问题特别难复现因为它在高帧率和低帧率下表现完全不同你在自己机器上测十分钟没事玩家一跑就出事。2.3 updatePosition、baseOffset、Warp 三个开关的真实含义updatePosition是这一整套问题的总闸。它默认为true意思是“transform 归我管你别碰”。你在 Update 里怎么改都没用因为它会在你之后覆盖。把它设为false之后Agent 退化成一台“路径计算器”它照样跑 A*、照样做避障、照样给出desiredVelocity和nextPosition但不再写你的 transform。这时候方向盘回到你手里代价是你得自己把真实位置喂回去否则 Agent 以为你还在原地路径会越算越偏。baseOffset前面说过是固定高度的偏移。它有一个很隐蔽的性质这个偏移是常数不参与重力不受碰撞影响。拿它做跳跃跳多高、什么时候落全靠你自己用曲线或者计时器控制物理世界完全不知情。Warp是瞬移加对齐它会把 Agent 强行放到指定位置并在附近采样一个合法的网格点。落地之后如果 Agent 已经不在网格上了这是把它救回来的标准手段。注意Warp有开销别每帧调。还有一个容易被忽略的agent.Move(Vector3 offset)它按给定向量移动会做碰撞滑动但它移动的仍然是 Agent 在网格上的位置你没法用它把角色抬离表面。想靠它做跳跃走不通。3. 四条能跑通的路子以及各自的适用边界3.1 路线一baseOffset 假跳最省事但只有视觉如果你的需求只是“角色原地蹦一下表达情绪”或者“受击时弹一下”那真没必要上物理。直接用一条曲线驱动baseOffset就行using System.Collections; using UnityEngine; using UnityEngine.AI; public class FakeJump : MonoBehaviour { [SerializeField] float height 0.8f; [SerializeField] float duration 0.45f; NavMeshAgent agent; float baseOffset; void Awake() { agent GetComponentNavMeshAgent(); baseOffset agent.baseOffset; } public void Play() { StopAllCoroutines(); StartCoroutine(Routine()); } IEnumerator Routine() { float t 0f; while (t duration) { t Time.deltaTime; float k Mathf.Clamp01(t / duration); // 正弦曲线起落两端速度不为零观感更弹 agent.baseOffset baseOffset Mathf.Sin(k * Mathf.PI) * height; yield return null; } agent.baseOffset baseOffset; } }这套写法的好处是零成本、不影响寻路、不会掉出网格跟其他系统完全不冲突。坏处也很明确碰撞体没动。角色看着跳起来了实际碰撞体还贴着地面能穿过矮墙的视觉缝隙但穿不过去能在跳跃中吃到地面的触发器。如果你的游戏有“跳过障碍物”这种玩法这条路直接排除。还有一个变体是把baseOffset和agent.height一起改让角色“蹲下钻过管道”之类的思路一样都是视觉层面的欺骗。3.2 路线二updatePosition false水平交给 Agent、垂直留给自己这是通用性最好的一条路也是我在正式项目里最常用的。核心思路是把“导航”和“位移”拆开Agent 只负责告诉我“该往哪个方向走、走多快”真正推角色的是我自己垂直方向完全由我掌控。具体做法是把agent.updatePosition和agent.updateRotation都关掉用agent.desiredVelocity拿期望速度用CharacterController.Move或Rigidbody.velocity施加位移然后把真实位置写回agent.nextPosition让 Agent 的路径跟着你走。这条路之所以可靠是因为它把责任划清了。水平方向上Agent 依然在做它擅长的事避障、绕路、贴边、过拐角垂直方向上重力、跳跃初速、落地检测全部在你自己手里用哪套物理都行。你甚至可以在空中改变水平速度做“空中微调”Agent 完全不会干涉。代价是你要自己补一堆东西贴地检测、斜坡处理、台阶、落地对齐、掉出网格后的救援。这些东西平时 Agent 帮你做了你一关它就得自己写。后面第 4 节我会把这几样逐个过一遍。3.3 路线三起跳瞬间关掉 Agent落地重新采样如果你的项目跳跃用得很少比如只有几处固定的“跳下平台”那最省代码的做法是起跳时直接agent.enabled false落地后Warp回网格再打开。void BeginJump() { agent.enabled false; // 这里放开物理让 Rigidbody 接管 rb.isKinematic false; rb.velocity new Vector3(rb.velocity.x, jumpSpeed, rb.velocity.z); } void OnGrounded() { rb.isKinematic true; if (NavMesh.SamplePosition(transform.position, out var hit, 3f, NavMesh.AllAreas)) { transform.position hit.position; } agent.enabled true; agent.Warp(transform.position); }这条路的风险要讲清楚。第一Agent 关掉的这段时间里它不参与避障其他 Agent 会从它身上穿过去如果你的游戏有多个 AI 同屏观感会很怪。第二重新启用的时候如果角色离网格太远Unity 会拒绝创建 AgentConsole 里会出现类似“Failed to create agent because it is not close enough to the NavMesh”的警告然后这个 Agent 就废了后面的SetDestination全部无效。第三频繁开关有开销别在每一帧里做。3.4 路线四OffMeshLink 做定点跳跃游戏里如果有那种“固定的断桥、固定的跨栏、固定的井盖”用 OffMeshLink 是最符合导航系统设计初衷的。你只需要在场景里放一个连接两端的 Link然后让 Agent 自己走过去触发的时候播一段跳跃动画。默认情况下 Agent 会自动沿 Link 线性插值过去观感像“滑过去”而不是“跳过去”。想要抛物线把agent.autoTraverseOffMeshLink关掉自己接管void Update() { if (agent.isOnOffMeshLink !traversing) { StartCoroutine(Traverse()); } } IEnumerator Traverse() { traversing true; OffMeshLinkData data agent.currentOffMeshLinkData; Vector3 start agent.transform.position; Vector3 end data.endPos Vector3.up * agent.baseOffset; float duration 0.6f; float t 0f; while (t 1f) { t Time.deltaTime / duration; Vector3 pos Vector3.Lerp(start, end, t); pos.y 1.2f * Mathf.Sin(Mathf.Clamp01(t) * Mathf.PI); // 抛物弧 transform.position pos; yield return null; } agent.CompleteOffMeshLink(); traversing false; }这套方案的优点是路径规划是“预知”的——AI 在算路的时候就知道这里需要跳会提前减速、播预备动作。缺点是只适用于固定点位玩家自由跳跃用不上。3.5 四条路线的横向对比方案是否真的离开地面能否越过障碍改动量推荐场景baseOffset 假跳否纯视觉否极小情绪动作、受击弹跳、演出updatePositionfalse 混合是是中玩家角色、需要自由跳跃关 Agent 落地重采样是是小少量固定跳点、简单 DemoOffMeshLink是受控是中AI 定点跳跃、断桥、跨栏选型的时候有个很实用的判断标准这个跳跃是玩家主动发起的还是路径上必然发生的。玩家主动发起的必须走路线二因为玩家可能在任意时刻、任意位置起跳路径上必然发生的走路线四让 AI 提前知道。4. 混合控制器落地时踩到的四个坑4.1 落地后 isOnNavMesh 变成 false之后所有寻路都哑了这是我把updatePosition关掉之后遇到的第一个坑而且它非常隐蔽——角色看起来一切正常能走能跳就是不再自动寻路了。打开 Console 才发现一堆红字SetDestination can only be called on an active agent that has been placed on a NavMesh。原因很直白你跳过了沟壑、跳上了高台落地的位置在 NavMesh 之外。Agent 依然在跑但它的内部位置已经无效了。修法是在落地的那一帧做一次重新采样void TryRebaseOnNavMesh() { if (agent.isOnNavMesh) return; if (NavMesh.SamplePosition(transform.position, out NavMeshHit hit, 3f, NavMesh.AllAreas)) { agent.Warp(hit.position); } else { // 附近完全没有网格说明掉出关卡了走复活/传送逻辑 Debug.LogWarning(落地位置附近没有 NavMesh需要走救援流程); } }SamplePosition的第三个参数是搜索半径我一般给 2 到 3 米。给太小会因为角色刚好站在网格边缘而采样失败给太大又可能把角色吸到一个完全不相干的位置比如从二楼被吸到一楼。这个值要结合你关卡里最窄的可行走区域来定。注意Warp之后角色的 transform 会被直接改掉如果这一帧里你还有相机跟随、位移插值之类的逻辑记得把顺序理顺否则相机会有一次明显的瞬移。4.2 nextPosition 喂了带高度的坐标角色开始原地抽搐第二个坑更恶心。我在空中也老老实实把transform.position含真实 y写回agent.nextPosition结果角色在空中开始左右抖动落地后还要抽半秒才恢复。原因是nextPosition期望的是一个“在网格上或者离网格很近”的位置。你在半空中y 差了一两米Agent 收到之后会尝试把你自己投影回去投影的结果又影响下一帧的desiredVelocity形成一个小幅震荡的反馈环。正确的写法是分状态回喂——在地面上给完整坐标在空中只给平面坐标把 y 保持为 Agent 自己上次的有效值void SyncAgent() { Vector3 p transform.position; if (cc.isGrounded) { agent.nextPosition p; } else { // 空中只同步 x/zy 沿用 Agent 记录的网格高度 agent.nextPosition new Vector3(p.x, agent.nextPosition.y, p.z); } }这么改之后抖动立刻消失。这个细节我看过的教程里基本没人提但它对观感的影响非常大。4.3 Rigidbody 和 NavMeshAgent 挂在同一个物体上很多人的第一反应是“跳跃是物理那就加个 Rigidbody”。加了之后发现角色能跳了但开始抖、开始穿模、偶尔被弹飞到天上。这是两个系统在抢同一个 transform。Rigidbody的物理积分在固定步长里跑它会把 transform 设成物理引擎算出来的位置NavMeshAgent在自己的更新里把 transform 设成路径上的位置。谁最后写谁赢而这两个的时序每帧都可能不一样所以表现就是随机抖动。如果你走路线二updatePosition false处理起来很简单让 Rigidbody 变 kinematic位置完全由 CharacterController 或者代码驱动物理只用来做触发器检测。如果你确实需要物理表现比如被爆炸击飞那就得在腾空期间关掉 Agent 的位置控制落地再打开别让两个系统同时在线。4.4 斜坡、台阶以及“跳跃中被拽回原位”的残影最后一个坑跟地形有关。CharacterController有个stepOffset默认 0.3 左右它让角色能自动迈上矮台阶。而 NavMeshAgent 在烘焙的时候是按“可行走表面”来切多边形的斜坡坡度超过烘焙时的 Max Slope 就不会被算进去。这两套判定标准不一致的时候会出现很诡异的现象角色在台阶上跳跃落地瞬间被推回台阶下面或者卡在台阶边缘原地蹬腿。我的处理办法是把三个参数对齐CharacterController.stepOffset调到 0.25 到 0.3CharacterController.slopeLimit和 NavMesh 烘焙时设的 Max Slope 保持一致比如都是 45 度agent.radius比controller.radius大一点点比如 controller 0.4、agent 0.5让导航在算路时预留余量避免角色贴着墙角走不过去。agent.height也要和controller.height对齐否则过门洞的时候导航认为能过、碰撞认为过不去角色就会在门口反复横跳。5. 一份可直接抄的 Agent 加跳跃混合控制器5.1 先约定好谁负责什么在贴代码之前把分工写成表格贴在项目文档里后面维护的人会感谢你职责归谁说明算路径、绕障碍、过拐角NavMeshAgentdesiredVelocity输出期望速度水平加速、减速本脚本MoveTowards平滑空中减弱操控重力、跳跃初速、贴地本脚本完全不管 Agent 怎么想实际位移与碰撞CharacterController统一入口避免双写朝向本脚本关掉updateRotation自己转更跟手位置回喂本脚本每帧nextPosition分地面/空中5.2 完整脚本using UnityEngine; using UnityEngine.AI; [RequireComponent(typeof(CharacterController))] [RequireComponent(typeof(NavMeshAgent))] public class NavMeshJumper : MonoBehaviour { [Header(水平移动)] [SerializeField] float maxSpeed 4.5f; [SerializeField] float accel 30f; [SerializeField] float turnSpeed 720f; [Header(跳跃)] [SerializeField] float jumpHeight 1.6f; [SerializeField] float gravity -22f; [SerializeField] float coyoteTime 0.12f; [SerializeField] float airControl 0.35f; [Header(调试)] [SerializeField] bool logState false; CharacterController cc; NavMeshAgent agent; Vector3 planarVel; // 世界空间水平速度 float verticalVel; // 只用 y float coyoteTimer; bool wantJump; void Awake() { cc GetComponentCharacterController(); agent GetComponentNavMeshAgent(); // 关键三行Agent 只算路不碰 transform agent.updatePosition false; agent.updateRotation false; agent.autoBraking false; } void Update() { if (Input.GetButtonDown(Jump)) wantJump true; StepPlanar(); StepVertical(); Vector3 motion planarVel Vector3.up * verticalVel; cc.Move(motion * Time.deltaTime); StepFacing(); SyncAgent(); } void StepPlanar() { // desiredVelocity 已包含避障结果且是平面向量 Vector3 target Vector3.ProjectOnPlane(agent.desiredVelocity, Vector3.up); float a cc.isGrounded ? accel : accel * airControl; planarVel Vector3.MoveTowards(planarVel, target, a * Time.deltaTime); if (planarVel.magnitude maxSpeed) planarVel planarVel.normalized * maxSpeed; } void StepVertical() { if (cc.isGrounded) coyoteTimer coyoteTime; else coyoteTimer - Time.deltaTime; if (wantJump coyoteTimer 0f) { // v sqrt(2 * g * h)保证起跳高度和 jumpHeight 一致 verticalVel Mathf.Sqrt(2f * Mathf.Abs(gravity) * jumpHeight); coyoteTimer 0f; } wantJump false; verticalVel gravity * Time.deltaTime; // 贴地时给一个小的下压防止斜坡上飘 if (cc.isGrounded verticalVel 0f) verticalVel -2f; } void StepFacing() { Vector3 flat new Vector3(planarVel.x, 0f, planarVel.z); if (flat.sqrMagnitude 0.01f) return; Quaternion target Quaternion.LookRotation(flat); transform.rotation Quaternion.RotateTowards( transform.rotation, target, turnSpeed * Time.deltaTime); } void SyncAgent() { Vector3 p transform.position; if (cc.isGrounded) { agent.nextPosition p; } else { // 空中只喂平面坐标避免触发 Agent 的投影回拉 agent.nextPosition new Vector3(p.x, agent.nextPosition.y, p.z); } if (cc.isGrounded) TryRebaseOnNavMesh(); if (logState) Debug.Log($ground{cc.isGrounded} vY{verticalVel:F2} pv{planarVel.magnitude:F2}); } void TryRebaseOnNavMesh() { if (agent.isOnNavMesh) return; if (NavMesh.SamplePosition(transform.position, out NavMeshHit hit, 3f, NavMesh.AllAreas)) agent.Warp(hit.position); else Debug.LogWarning(落地位置附近没有可用的 NavMesh); } public void SetDestination(Vector3 worldPos) { if (agent.isOnNavMesh) agent.SetDestination(worldPos); } }5.3 参数怎么标定以及三个便宜的调试开关jumpHeight和gravity是配对的改一个另一个的观感就变了。我习惯先定跳跃高度比如 1.6 米大约一个身位的 1.2 倍再反推初速度v √(2 × 22 × 1.6) ≈ 8.4 m/s滞空时间大约 0.76 秒。拿这个滞空时间乘以水平速度 4.5 m/s能跳过的水平距离大约 3.4 米。关卡里设计沟壑宽度的时候这个数就是你的上限超过 3 米就得加二段跳或者加速道具。coyoteTime是“土狼时间”作用是你刚走下平台的一小段时间内还允许起跳。0.1 到 0.15 秒之间手感最好太长了会出现“明明已经掉下去还能凭空起跳”的诡异感。调试开关我通常留三个一个在 Scene 视图画desiredVelocity和planarVel两条射线直观看到 Agent 想让你去哪、你实际往哪走一个把cc.isGrounded和agent.isOnNavMesh打到屏幕上还有一个是按键切换agent.updatePosition的开关用于排查“到底是不是 Agent 在捣鬼”。这三个加起来不到二十行但排查这类问题的效率能翻好几倍。最后分享一个我自己项目里的体会把“导航”和“位移”当成两件事之后很多原本很难处理的需求都变得顺理成章。空中冲刺、被击飞、踩弹跳板、从高处跳下、坐电梯——这些“垂直方向有变化”的行为只要把垂直那一维从 Agent 手里拿回来剩下的就是普通的运动学和状态机问题。反过来如果你一直想着“让 Agent 支持跳跃”会在baseOffset、Warp、isOnOffMeshLink之间来回打转越改越乱。