>

# Unity CharacterController 落地穿墙/卡地面修复方案

典型案例素材

角色高速下落（重力累积速度峰值约 -30 m/s），落地瞬间穿入地面或贴墙下移时卡进墙体，触发 OnControllerColliderHit 异常抖动。

原因分析

1. 位移过大穿透：Move() 单帧位移超过碰撞半径时，CC 的胶囊扫掠检测失效，直接穿过碰撞体。30 m/s × 0.016s ≈ 0.5m，地面碰撞体若只有薄 BoxCollider（厚度 0.3m）必穿。

2. 每帧速度累加未清零：落地后 verticalVelocity 继续累加负值，下一帧仍在“推”角色入地。

3. 斜面/边缘滑动：Move 碰撞后 Unity 会自动滑移，贴墙时把水平位移分量转成垂直下陷。

修复代码

```csharp

public class SafeCCMove : MonoBehaviour

{

CharacterController cc;

public float gravity = -20f;

float vy;

void Awake() => cc = GetComponent<CharacterController>();

void FixedUpdate() // 用 FixedUpdate 保证物理步长稳定

{

Vector3 move = new Vector3(Input.GetAxis("Horizontal"), 0, Input.GetAxis("Vertical")) * 5f;

// 1. 限制单帧最大位移，防止穿透

const float maxStep = 0.2f;

Vector3 delta = move + Vector3.up * vy;

if (delta.magnitude > maxStep) delta *= maxStep / delta.magnitude; // 分帧位移

// 2. 碰撞标志检测

bool wasGrounded = cc.isGrounded;

// 3. 分轴移动，避免斜面滑移下陷

cc.Move(Vector3.up * delta.y * Time.fixedDeltaTime);

cc.Move(new Vector3(delta.x, 0, delta.z) * Time.fixedDeltaTime);

// 4. 重力管理：落地清零速度

if (cc.isGrounded && vy < 0) vy = -1f; // 小负值保持贴地，不用0

else vy += gravity * Time.fixedDeltaTime;

if (Input.GetButtonDown("Jump") && cc.isGrounded) vy = 8f;

}

}

```

配套设置

• 地面碰撞体改用 MeshCollider/厚 BoxCollider（≥0.5m），避免薄面穿透；
• CC 的 Skin Width 设 0.02~0.08，Min Move Distance 保持默认 0.001；
• 角色胶囊 Center 置于模型几何中心，Radius 略大于模型半径 0.05；
• 若仍偶发卡墙，在 OnControllerColliderHit 中检测 `hit.normal.y