我的Godot 3D移动控制器无法工作，如何排查故障？

核心问题定位 #

你说_ready函数加了print没输出，说明脚本根本没被执行，这是所有问题的根源，先解决这个，再处理鼠标和移动功能。

第一步：确认脚本挂载正确 #

• 打开你的场景，选中那个RigidBody3D节点（不是子节点），看右侧检查面板的「脚本」栏，是否已经把你的gdscript文件拖进去了。如果是空的，或者挂错了节点，脚本肯定不会运行。
• 检查脚本第一行extends RigidBody3D，确保和你场景中节点的类型完全一致。如果你用的是Godot 4.x里的CharacterBody3D（现在做角色控制器更常用这个），那这里要改成extends CharacterBody3D，否则脚本无法正确绑定。

第二步：验证脚本是否加载 #

• 打开Godot的输出面板：顶部菜单点「调试」→「显示调试面板」→勾选「输出」，别让输出被隐藏了。
• 在脚本的最顶部（extends下面）加一行print("控制器脚本加载成功")，运行游戏，如果输出面板能看到这句话，说明脚本正常运行了；还是看不到的话，回到第一步重新检查挂载。

第三步：修复鼠标捕获问题 #

脚本运行后，直接在_ready里设置鼠标捕获可能不生效（Godot要求鼠标捕获需要用户交互触发，比如点击窗口），改成用户点击后再捕获：

func _unhandled_input(event):
    # 点击窗口后自动捕获鼠标
    if event is InputEventMouseButton and event.pressed:
        Input.set_mouse_mode(Input.MOUSE_MODE_CAPTURED)
    
    # 原有的鼠标移动处理
    if event is InputEventMouseMotion:
        if Input.get_mouse_mode() == Input.MOUSE_MODE_CAPTURED:
            twist_input = -event.relative.x * mouse_sensitivity
            pitch_input = -event.relative.y * mouse_sensitivity

第四步：检查其他功能的必要设置 #

• 输入映射：打开「项目」→「项目设置」→「输入映射」，确认left、right、forward、backward、jump、ui_cancel这些动作都绑定了对应的按键（比如jump绑定空格，left绑定A键等），没绑定的话输入会无效。
• 跳跃信号连接：_on_area_3d_area_entered是Area3D的area_entered信号回调，需要手动连接：右键场景里的Area3D节点→「连接信号」→找到area_entered→选择你的脚本，然后选_on_area_3d_area_entered函数，否则落地后不会重置can_jump。

补充：RigidBody3D vs CharacterBody3D #

如果你的角色是第一/第三人称控制器，更推荐用CharacterBody3D（Godot 4.x新增），它的移动逻辑更适合角色控制，而RigidBody3D是物理驱动的，新手容易出现移动卡顿、飘的问题。如果要切换，记得把脚本的extends改成CharacterBody3D，然后把apply_central_force换成move_and_slide这类方法。

内容的提问来源于stack exchange，提问作者Mike Lit