React Three.js 3D项目WASD键盘控制角色移动失效问题

核心问题与修复方案 #

以下是按影响优先级排序的错误点，覆盖完全无法移动、移动逻辑异常两类问题：

• 按键判断逻辑错误，多键/单键识别失效
  现有代码用else if链判断WASD按键状态，只要W键按下，S/D/A的判断逻辑会被直接跳过，斜向移动（比如W+D同时按）完全失效；如果按键事件触发顺序异常，单按A/D也可能被前置判断拦截。
  错误代码：

  if (w == true) {
    vertical += 1;
    console.log("Pressed w");
  } else if (s == true) {
    vertical -= 1;
    console.log("Pressed s");
  } else if (d == true) {
    horizontal += 1;
    console.log("Pressed d");
  } else if (a == true) {
    horizontal -= 1;
    console.log("Pressed a");
  }
  

  修复为独立判断，去掉else串联：

  if (w) vertical += 1;
  if (s) vertical -= 1;
  if (d) horizontal += 1;
  if (a) horizontal -= 1;
  

• useVariable状态不同步（90%概率导致完全不动的根因）
  你用useVariable存按键状态是为了规避useFrame的闭包陷阱，但如果这个Hook没有在状态更新时同步ref值，input.current会永远停留在初始的全false状态，所有按键判断分支都不会触发，自然不会产生移动。
  请检查你的useVariable实现是否符合标准逻辑，缺少同步逻辑会直接导致输入失效：

  import { useRef, useEffect } from "react";
  export const useVariable = (value) => {
    const ref = useRef(value);
    // 每次值变化时同步更新ref
    useEffect(() => {
      ref.current = value;
    }, [value]);
    return ref;
  };
  

• 速度计算逻辑混淆，实际移动速度被压缩到接近静止
  api.velocity.set是物理引擎提供的瞬时速度设置接口，单位为米/秒，物理引擎会自动根据帧间隔delta计算帧内位移，不需要手动乘delta。你现在给x/z轴速度乘delta，相当于把速度缩小约60倍；同时你设置的speed=300是力/冲量的量级，作为速度值会远超正常范围。
  错误代码：

  // 顶部常量
  const speed = 300;
  // useFrame内设置速度
  api.velocity.set(
    velocity.x * delta,
    state.current.vel[1],
    velocity.z * delta
  );
  

  修复方案：把顶部speed常量改为5（符合第一人称正常走路速度3-6m/s的范围），去掉速度赋值时的delta乘法：

  const speed = 5;
  // useFrame内设置速度
  api.velocity.set(
    velocity.x,
    state.current.vel[1],
    velocity.z
  );
  

• 方向向量计算错误，移动方向偏移/无水平分量
  现有代码取相机本地矩阵camera.matrix计算方向，只要相机存在父节点变换，拿到的方向值就会错误；同时右方向直接取矩阵列，没有做水平归一化，玩家上下视角移动时，水平移动的分量会被垂直分量稀释，抬头/低头时会出现按移动键不动的情况。
  错误代码：

  let forward = new Vector3();
  forward.setFromMatrixColumn(camera.matrix, 0);
  forward.crossVectors(camera.up, forward);
  
  let right = new Vector3();
  right.setFromMatrixColumn(camera.matrix, 0);
  

  修复为直接使用世界方向计算，强制锁定水平移动：

  // 获取相机面朝的世界方向，去掉y分量保证始终在水平面移动
  const forward = new Vector3();
  camera.getWorldDirection(forward);
  forward.y = 0;
  forward.normalize();
  // 右方向 = 上方向叉乘前方向，归一化保证向量长度为1
  const right = new Vector3();
  right.crossVectors(camera.up, forward).normalize();
  

• 斜向速度限制逻辑无效
  clampLength方法第一个参数是最小向量长度，向量长度不可能为负数，你传入-speed相当于完全没做速度限制，斜向移动时速度会比正向快1.4倍。修复为最小长度传0：

  velocity.clampLength(0, speed);
  

可选优化点 #

• 把useFrame内每帧新建的Vector3、Raycaster实例提到useRef中初始化后复用，避免频繁触发GC造成卡顿。
• 地面检测射线长度调整为0.3，避免高速下落时检测不到地面导致跳跃连跳失效。
• 键盘事件监听中加e.preventDefault()，阻止空格键触发页面滚动、WASD触发页面滚动等默认行为，避免游戏失焦。

内容的提问来源于stack exchange，提问作者Daniciuc Razvan