如何从 Unity 旧版 Input Manager 迁移到 Input System 而不破坏控制
概要
将 Unity 6 项目从旧版 Input Manager 迁移到 Input System,同时保持玩家控制、UI 和遗留 Input 调用正常工作。
你安装了 Input System,按下 Play,Unity 抛出错误:你正在尝试使用 UnityEngine.Input 类读取输入,但 Active Input Handling 已经指向 Input System 包。或者 Play Mode 启动后,暂停菜单不再接收任何点击。
本文展示了将现有 Unity 6 项目从旧版 Input Manager 迁移到新 Input System 的安全顺序,不会破坏控制或 UI。保持两个后端同时开启,替换你的 Input 调用,修复 EventSystem,然后只在一切仍正常工作时才关闭旧管理器。这些步骤遵循截至 2026 年 11 月 20 日的官方 Input System 文档。从 Package Manager 安装当前的 Input System 包。不要固定本文中的包版本,因为会有更新的版本发布。
为什么要在 Unity 6 中迁移
Unity 手册现在将内置的 Input Manager 视为遗留功能。它已被弃用,不推荐用于新项目,Unity 表示将在未来版本的编辑器中移除它。旧管理器仍然可用,以便现有项目能够继续运行。有计划的切换总比等到未来升级为你移除旧后端要好。
在迁移时保持两个后端同时开启
如果你的项目不包含 Input System,打开 Window > Package Manager,切换到 Unity Registry,并安装 Input System 包。从 Unity 6.1 开始,一些项目模板已经添加了它。空项目通常不包含。
安装过程中,Unity 会询问是否启用 Input System 后端并禁用 Input Manager 后端。如果选择 Yes,编辑器将重启并仅激活新系统。每个遗留的 Input.GetAxis 或 Input.GetButton 调用都会失败,仍使用旧输入模块的 uGUI 菜单也会随之失败。
请自己设置后端。转到 Edit > Project Settings > Player,打开 Other Settings,将 Active Input Handling 设置为 Both。编辑器将重启。在该模式下,Unity 同时定义 ENABLE_LEGACY_INPUT_MANAGER 和 ENABLE_INPUT_SYSTEM,因此新旧代码可以并存。
#if ENABLE_INPUT_SYSTEM
// New Input System backends are enabled.
#endif
#if ENABLE_LEGACY_INPUT_MANAGER
// Old Input Manager backends are enabled.
#endif
将 Both 视为过渡方案。保持开启状态直到你自己的脚本、EventSystem 和任何第三方资源都已迁移。只有在 Play Mode 和构建版本都能正常运行,没有异常且 UI 正常工作后,才切换到 Input System Package (New)。
用 Actions 替换 GetAxis 和 GetButton
推荐的工作流程是读取命名 action,而不是原始设备按钮。除非你需要多个 action 资源,否则将单个资源分配为项目范围的 action。
打开 Edit > Project Settings > Input System Package,如果没有设置,创建或分配默认的项目范围 action。默认包含 Player 地图和 UI 地图,包含诸如 Move(Vector2 值)和 Jump 等 action,已经为键盘、鼠标、gamepad、触摸和 XR 绑定。你可以通过 InputSystem.actions 访问它们。它们默认启用,并在启动时预加载,在编辑器中每次进入 Play Mode 时也会预加载。
查找每个 action 一次,然后每帧读取它。像 Input.GetAxis("Horizontal") 那样每次按名称查找 action,在新 API 中是慢速路径。
using UnityEngine;
using UnityEngine.InputSystem;
public class PlayerMovement : MonoBehaviour
{
InputAction moveAction;
InputAction jumpAction;
void Start()
{
moveAction = InputSystem.actions.FindAction("Move");
jumpAction = InputSystem.actions.FindAction("Jump");
}
void Update()
{
Vector2 move = moveAction.ReadValue<Vector2>();
if (jumpAction.WasPressedThisFrame())
{
// jump
}
}
}
UnityEngine.InputSystem 命名空间中的名称与旧调用的对应关系如下:
Input.GetAxis("Horizontal")和Input.GetAxis("Vertical")变成moveAction.ReadValue<Vector2>()Input.GetButton("Jump")变成jumpAction.IsPressed()Input.GetButtonDown变成WasPressedThisFrame()Input.GetButtonUp变成WasReleasedThisFrame()Input.GetKey(KeyCode.Space)变成Keyboard.current.spaceKey.isPressedInput.GetMouseButton(0)变成Mouse.current.leftButton.isPressedInput.mousePosition变成Mouse.current.position.ReadValue()
如果你想让控制感觉相同,有两个细节很重要。默认的 Move action 是 2D 值,所以旧的 Horizontal 和 Vertical 轴变成了一个向量,而不是两个浮点数。而且 ReadValue 不应用旧的 Gravity 和 Sensitivity 平滑,所以按键或按钮会立即达到其完整值。如果你的移动依赖于该渐变,你需要有意识地重新创建它。Input.GetAxisRaw 没有直接等效项。ReadUnprocessedValue() 仅在 action 附加了处理器时才与 ReadValue 不同。
诸如 Keyboard.current 之类的直接设备读取是快速替代方案,而不是长期工作流程,并且当硬件缺失时当前设备可以为 null。
一些较旧的 Input Manager 功能仍然取决于你的 Unity 版本。从 Unity 6.4 开始,MonoBehaviour 鼠标事件函数(如 OnMouseDown)可与 Input System 配合使用。在早期的 Unity 6 版本中,一旦仅激活新后端,它们可能无效。如果你的项目使用位置、指南针或设备方向,请在关闭旧管理器之前查看适用于你的编辑器的 Input System 文档。IMGUI(OnGUI)与 Input System 不兼容,因此以这种方式构建的调试菜单可能需要保持在 Both 状态。
保持 UI 正常工作
如果你使用 Unity UI(uGUI),你始终需要在 EventSystem 上使用输入模块来将 Input System 输入到 UI。较旧的 StandaloneInputModule 仍与旧版 Input Manager 通信。当 Active Input Handling 设置为仅新包时,该模块是 UnityEngine.Input 异常的常见来源。
在场景中选择 EventSystem。如果安装了 Input System 包,Inspector 会提供一个按钮,将 StandaloneInputModule 替换为 InputSystemUIInputModule。新模块预配置了默认 UI action。当 Active Input Handling 已设置为新包或 Both 时,如果你在场景中放置新的 uGUI 元素,Unity 也会自动添加新模块。
UI Toolkit 有所不同。从 Unity 2023.2(包括 Unity 6)开始,UI Toolkit 可以从项目范围的 action 读取 UI action,无需额外模块。当 UI Toolkit 和 uGUI 共享同一场景时,你确实需要 InputSystemUIInputModule 加 EventSystem。
如果你还使用 PlayerInput 组件,将相同的 action 资源分配给 PlayerInput 和 InputSystemUIInputModule,并在 PlayerInput 上设置 UI Input Module 字段。然后相同的设备分配同时驱动玩家和 UI。如果你的脚本在使用 PlayerInput 时读取 action,请读取 PlayerInput.actions,而不是 InputSystem.actions,因为 PlayerInput 为每个玩家的设备保留了一个过滤副本。
异常和遗留的 Input 调用
运行时错误通常显示:InvalidOperationException: You are trying to read Input using the UnityEngine.Input class, but you have switched active Input handling to Input System package in Player Settings. 当 Active Input Handling 设置为 Input System Package (New) 且某些东西仍调用 UnityEngine.Input 时会出现此错误。
在更改随机脚本之前先阅读堆栈跟踪。它通常从 StandaloneInputModule 或 BaseInput.GetButtonDown 开始,而不是在你的移动类中。修复 EventSystem 后,在你自己的代码中搜索 Input.GetAxis、Input.GetButton、Input.GetKey、Input.GetMouseButton 和 Input.mousePosition。然后检查第三方资源和插件。将 Active Input Handling 设置回 Both 是有效的临时步骤。持久的修复是迁移调用者或更新插件。
何时值得使用 PlayerInput
PlayerInput 组件是可选的。当你想要 Send Messages(OnJump、OnMove(InputValue value))、Invoke Unity Events 或用于本地多人游戏的 PlayerInputManager 时添加它。已经在 Update 中轮询的单人游戏可以继续使用 FindAction 和 ReadValue。
简短的迁移检查清单
- 从 Package Manager 安装当前的 Input System 包,然后将 Active Input Handling 设置为 Both。
- 创建或分配默认的项目范围 action。
- 替换你自己的
Input调用。查找每个 action 一次,然后每帧读取它。 - 如果你使用 uGUI,将
StandaloneInputModule替换为InputSystemUIInputModule,并使用键盘和 gamepad 点击菜单。 - 根据你的 Unity 版本检查
OnMouse事件、触摸、位置、指南针和 IMGUI。 - 更新仍调用
UnityEngine.Input的插件,或在存在修复之前保持 Both 开启。 - 当 Play Mode 和构建版本运行时没有异常且 UI 正常工作时,将 Active Input Handling 设置为 Input System Package (New)。
在切换最后一个开关之前,通过移动、菜单和屏幕按钮进行测试。输入是客户端引擎主题。horizOn 是一个游戏后端,具有用于账户、云存档、排行榜和游戏内新闻的 Unity SDK。迁移 Input System 不会改变你使用该 SDK 的方式,也不会替换或包装 Unity 的输入堆栈。