Unity 的新输入系统Input System是 Unity 2019 年开始正式入包的一套输入方案用来替代老旧的 Input Manager。我在项目里从“老一套”迁到新系统的时候第一反应是没事折腾什么等真把 Action Map、Action、Binding 这些概念理顺之后我只想说真香。这篇文章不打算照着官方文档念我会把安装、配置、代码接入、常见报错这些在实际项目中会用到的东西都拆开讲一遍尽量给你一套可以直接照抄的流程。如果你正卡在“装上包但是没有反应”“新 API 一直报错”这种阶段或者项目刚起步想一步到位这篇文章应该能帮上忙。1. 新输入系统到底替我们解决了什么1.1 旧输入管理器的硬伤新系统出来之前Unity 的输入方式说白了就是Input.GetAxis(Horizontal)这一套。代码确实很简单但真正做起项目来你会撞上一堆暗坑字符串是硬编码的Horizontal拼错一个字母编译器不会报错游戏里就是没反应键盘、手柄、移动触屏要分开适配手柄玩家改键位还得自己写一套保存和读取逻辑复合操作比如“按上攻击”出必杀技基本要靠自己拼状态机VR、触控笔这类新设备的支持旧系统几乎帮不上忙。旧系统真正让人难受的是“输入来源”和“游戏逻辑”完全耦合。你想要支持玩家自定义键位必须自己写一套映射类把“物理按键”翻译成“游戏动作”。很多项目里这套映射代码东一块西一块最后变成谁也看不懂的状态。新输入系统就是冲着这些痛点来的。它把“物理按键”和“语义动作”彻底拆开绑定关系交给可视化编辑器代码里只管消费“动作事件”。你不用再盯着W键想逻辑了你想的是Move这个动作。1.2 新系统的核心设计解耦之后带来的连锁收益新输入系统最重要的设计思路就是把声音、键盘、手柄、触屏这些物理输入来源和游戏内语义动作彻底解耦。打个比方。旧系统像是餐厅后厨直接写死“今天用西门子的烤箱”明天想换美的整个后厨电路都要改。新系统则像是规定了“我要一台能烤到 200 度的烤箱”至于哪个牌子、什么型号配置表里随便换后厨不动。这个解耦带来的直接好处很实际换平台只换 Binding 配置逻辑代码不动玩家改键不用重新编译运行时用重绑定 API 就能完成多套操作方案键鼠、手柄、触屏可以通过 Control Scheme 随时切换输入事件是回调式的不用每帧反复GetAxisPlayerInput 组件原生支持本地多人每个玩家绑定一套设备。下面这个对比表基本能概括两套系统的差异对比项旧 Input Manager新 Input System输入来源固定映射改键困难Action Binding可视化配置可运行时重映射设备支持键鼠为主手柄触屏支持弱键盘、鼠标、手柄、触屏、XR 控制器全覆盖事件机制每帧轮询started / performed / canceled 事件回调多玩家基本没有PlayerInput 原生支持复合绑定自己写逻辑内置 2D Vector、Dpad、Button 等复合绑定运行时可调试弱Input Debugger 可视化调试这段对你意味着什么简单说新输入系统学习成本比旧系统高一些因为它不再是“写到哪算哪”的脚本而是要先做配置再用配置驱动代码。但一旦你适应这个节奏后面所有输入相关的工作都会轻松很多。2. 安装与启用开工前必须过的两道关2.1 通过 Package Manager 安装新输入系统是官方 Package不是默认内置到每个项目里的但你不需要去官网下载什么插件直接在包管理器里装就行。操作路径打开菜单Window Package Manager左上角包类型选Unity Registry搜索Input System点Install装最新的稳定版等编译完成。如果你习惯用 manifest.json 管理依赖也可以直接在Packages/manifest.json里加一行依赖{ dependencies: { com.unity.inputsystem: 1.7.0 } }Unity 启动时会自动解析并安装。我自己更推荐用 Package Manager 操作因为你可以直接看到版本号、更新时间、依赖关系心里更踏实。装完之后别急着写代码。还有一道关键的开关等着你。2.2 Active Input Handling新旧系统的总开关装完包之后进Project Settings Player Other Settings往下拉找到Active Input Handling。这里有三个选项选项含义适用场景Input Manager (Old)只用旧系统老项目短期不想动Input System Package (New)只用新系统新项目或旧代码已清理干净Both两套同时启用迁移过渡期新旧代码并存我给的建议新项目直接选Input System Package (New)不要给自己留退路如果项目里还有老代码在用Input.GetKey或者用了依赖旧 API 的第三方插件就选Both过渡。这里有一个极其容易踩的坑改完Active Input Handling必须彻底重启 Unity Editor不是退出场景、不是切回主窗口而是把整个编辑器关掉重开。不重启就直接用新 API你有大概率会撞到后面第六节里说的那个InvalidOperationException。我同事以前装完包改了设置不重启在脚本里死活找不到UnityEngine.InputSystem这个命名空间还怀疑是包没装上。其实包早就装好了就是设置没生效。提示切换 Active Input Handling 之后所有 C# 脚本会重新编译。如果项目很大第一次编译会有点慢这很正常耐心等它编译完不要中途去取消。2.3 创建 Input Action Asset新输入系统里一切配置的中心是 Input Action Asset也就是.inputactions文件。它把你游戏里会用到的所有动作和物理按键的映射关系都放在这个文件里管理。创建方式在 Project 窗口空白处右键选择Create Input Actions生成一个.inputactions文件给它起个名字比如GameInputActions。双击打开这个文件会弹出 Input Action 编辑面板。第一次打开你会看到默认生成了一个 Action Map 和一个 Action。别急着删先理解面板上这几层概念后面就好办了。3. Action 资产把三层概念一次捋清楚3.1 Action Map一组动作的集合Action Map 是一组相关动作的集合。你可以想象成不同“游戏状态”下的操作面板Gameplay移动、跳跃、攻击、交互UI导航、确认、返回Menu暂停菜单里的上下左右选择和确认。把不同状态的动作放进不同 Map切换状态时整体启用或禁用会非常干净。举个例子玩家在战斗中按 Alt 弹出暂停菜单如果GameplayMap 还在启用状态角色可能还会继续移动甚至还会开枪。所以切换状态时必须做整体切换playerInput.SwitchCurrentActionMap(UI);或者手动控制 Map 的启用与禁用inputActions.Gameplay.Disable(); inputActions.UI.Enable();在实际项目里Map 别建太多。我见过有人把一个游戏的所有动作塞进一个 Map第一个原因就是懒第二是图省事结果到了后期切换状态全是 bug。合理的 Map 划分应该跟你的游戏状态机保持一致。3.2 Action游戏世界里的语义动作Action 是真正传达给游戏逻辑的东西。比如Move动作物理按键可以是 W/A/S/D也可以是手柄左摇杆但对游戏来说它就是一个Vector2方向的输入。Action 有三种类型Action Type说明典型用途Value持续读值比如 Vector2、float移动轴、扳机力度Button瞬间触发事件按下、抬起跳跃、射击、交互Pass Through不过滤原样透传输入特殊姿态、调试数据采集关键要搞清楚Value和Button的区别Button更强调“事件”。比如跳跃你不是每帧去读“空格按没按”而是等待一个“按下”事件被触发Value更适合每帧采样。比如移动摇杆你希望知道当前摇杆推了多少。所以做移动用ValueVector2做跳跃用Button 监听performed事件。乱选类型会导致行为诡异比如把移动做成了 Button你会发现角色只能走一下停一下。3.3 Binding把物理输入映射到动作上每个 Action 可以挂多个 Binding。以Move为例你可以挂四个键盘 BindingW/A/S/D再挂一个手柄左摇杆 Binding完全没问题。在编辑面板里点Add Binding会弹出一个设备通道列表覆盖键盘、鼠标、手柄、触屏、XR 控制器等。找到你想要的按键或摇杆选中即可。这里有几个非常实用的配置经验Binding 的Composite类型里有一个2D Vector可以把“上、下、左、右”四个方向绑到一个 Vector2 上适合做通用平台移动Interactions面板可以给 Action 添加Press、Hold、Tap等交互定义。比如Hold1 秒后再触发适合做蓄力攻击Processors面板可以在输入进入游戏逻辑前做处理比如Normalize、Scale等。配置完之后一定要点Save Asset。我早期经常改完 Binding 不保存就切出去写代码结果代码怎么都读不到输入排查了半天发现资产根本没存上编辑器一刷新就全丢了。3.4 Control Scheme一键切换设备方案Control Scheme 解决的是“同一份输入资产支持不同设备类型”的问题。比如玩家在电脑上用键鼠插上手柄以后希望优先用手柄操作拔掉手柄再自动回到键鼠。在资产编辑器左上角Control Schemes里可以新建KeyboardMouse和Gamepad两个方案。创建之后每个 Binding 上都可以勾选它属于哪个方案。运行时切换方案也很简单inputActions.bindingMask InputBinding.MaskByGroup(Gamepad);如果你用了 PlayerInput 组件设备插入和断开时它会自动处理切换。对于 PC 游戏这基本是必备能力不然玩家插了手柄还要自己去设置里选设备体验会差很多。4. 代码接入的三种主流方式4.1 方式一序列化字段拖引用最直观的方式适合快速原型。在 MonoBehaviour 里声明InputActionReferenceusing UnityEngine; using UnityEngine.InputSystem; public class PlayerMovement : MonoBehaviour { [SerializeField] private InputActionReference moveAction; [SerializeField] private InputActionReference jumpAction; private void OnEnable() { moveAction.action.Enable(); jumpAction.action.Enable(); } private void OnDisable() { moveAction.action.Disable(); } private void Update() { Vector2 move moveAction.action.ReadValueVector2(); transform.position new Vector3(move.x, 0f, move.y) * Time.deltaTime; } }然后回到 Inspector把.inputactions资产里对应的Move、Jump动作直接拖到字段上就行。优点简单直接字段类型清晰适合快速验证。缺点一个字段只对应一个动作游戏动作多了字段数量会爆炸。4.2 方式二生成 C# Class这是我个人最推荐的方式。选中.inputactions资产在 Inspector 最下方勾选Generate C# Class设置好类名和命名空间点ApplyUnity 会自动生成一个以资产名为基础的类文件。生成之后代码里直接实例化这个类using UnityEngine; using UnityEngine.InputSystem; public class PlayerMovement : MonoBehaviour { private GameInputActions inputActions; private Vector2 moveInput; [SerializeField] private float moveSpeed 5f; private void Awake() { inputActions new GameInputActions(); } private void OnEnable() { inputActions.Gameplay.Move.performed OnMove; inputActions.Gameplay.Move.canceled OnMoveCanceled; inputActions.Gameplay.Jump.performed OnJump; inputActions.Enable(); } private void OnDisable() { inputActions.Gameplay.Move.performed - OnMove; inputActions.Gameplay.Move.canceled - OnMoveCanceled; inputActions.Gameplay.Jump.performed - OnJump; inputActions.Disable(); } private void Update() { Vector3 direction new Vector3(moveInput.x, 0f, moveInput.y); transform.position direction * (moveSpeed * Time.deltaTime); } private void OnMove(InputAction.CallbackContext context) { moveInput context.ReadValueVector2(); } private void OnMoveCanceled(InputAction.CallbackContext context) { moveInput Vector2.zero; } private void OnJump(InputAction.CallbackContext context) { if (context.performed) { // 跳跃逻辑写到这 } } }生成类的核心价值是类型安全动作名、方法名全是编译期检查拼错了 IDE 立刻标红比字符串方案靠谱一万倍。而且每个动作对应的性能开销也更可控。4.3 方式三PlayerInput 组件如果你的项目需要本地多人、设备配对、控制方案切换直接用PlayerInput组件最合适。在场景里给玩家角色挂上PlayerInput组件然后在 Inspector 里关联Input Actions资产。Behavior有三种选择Send Messages、Invoke Unity Events、Invoke C Sharp Events。以Send Messages为例你只需要按动作名写同名方法public class PlayerController : MonoBehaviour { public void OnMove(InputAction.CallbackContext context) { Vector2 move context.ReadValueVector2(); // 移动逻辑 } public void OnJump(InputAction.CallbackContext context) { if (context.performed) { // 跳跃逻辑 } } }注意Send Messages模式对方法签名有要求。方法名必须和 Action 名完全一致参数必须是InputAction.CallbackContext。如果回调没触发先检查名字是否对得上再检查组件上有没有正确绑定 Action Map。三种方式怎么选我的建议小项目、原型、验证玩法方式一正式项目、一个人维护代码方式二类型安全且代码清晰本地多人、设备频繁插拔、玩家加入离开直接用 PlayerInput省掉自己管理设备配对的痛苦。5. 生命周期管理与事件回调的正确姿势5.1 Enable 与 Disable 的配对时机新输入系统有一个特性动作在被Enable之前是不会反馈任何输入的。这意味着你必须在恰当的时机启用动作。最稳妥的生命周期搭配是Awake里创建实例OnEnable里订阅事件并EnableOnDisable里取消订阅并DisableOnDestroy里做最后的清理释放资源。养成这个习惯可以避免 MonoBehaviour 被禁用时角色还在响应输入。尤其做 UI 暂停菜单时如果你不把GameplayMap 关掉角色可能会在你读取菜单的时候继续移动玩家体感会非常怪。5.2 CallbackContext事件背后的状态信息每次动作触发事件回调参数都是一个InputAction.CallbackContext它是你读取输入状态的主要入口。常用成员成员含义context.phase当前阶段Started / Performed / Canceledcontext.started该帧动作开始context.performed该帧动作完成触发context.canceled该帧动作取消或松开context.ReadValueT()读取当前动作的值context.control触发事件的物理控件可以判断来源设备context.action当前动作对象一个容易出错的地方是区分started和performed。对于 Button 型动作按下瞬间通常started和performed都会触发。如果你想在“按键被按下”时只处理一次就在performed里做如果你想处理“按下后持续按住”的逻辑用started配合读取状态会更好。另外context.control在排查设备问题时很好用。比如玩家用手柄还是键鼠触发的事件直接判断这个值就行不用自己再维护一套设备状态。5.3 轮询还是事件别每帧 ReadValue 读个不停新输入系统保留了ReadValue这种轮询方式但如果在Update里对Value类型的动作频繁调用ReadValue性能不会比旧系统好多少依然每帧做设备状态查询和绑定解析。更好的模式是事件驱动。拿移动举例performed事件里把最新移动向量保存到成员变量canceled事件里把移动向量清零Update里只读取这个成员变量用来驱动角色移动。跳跃这种低频动作更简单直接在performed回调里触发逻辑连 Update 都不用来回读。我见过有些项目把十几个动作全部在 Update 里ReadValue逻辑混成一大坨后面改成事件驱动代码清晰了不少性能也更稳定。当然特殊场景还是有轮询需求的比如你想在游戏启动时检测“这一帧玩家按了任意键进入主菜单”直接用InputSystem.onAnyButtonPress更合适。6. 常见问题与排查实例6.1 报错You are trying to read Input using the UnityEngine.Input class这是新系统最著名的报错之一。暴力的意思是你当前的Active Input Handling已经切到了新系统但代码里还在调Input.GetKey、Input.GetAxis这类旧 API。解决办法有三种把旧代码改成新 API在 Player Settings 把Active Input Handling改成Both让旧 API 重新可用改完设置后重启编辑器。如果你选Both要注意新旧系统同时启用会增加一层事件分发开销虽然不大但长期还是建议尽早把旧代码清理干净。6.2 UI 点击没反应EventSystem 组件要换新系统下 UI 不响应点击十有八九是 EventSystem 上挂的还是旧的Standalone Input Module。需要换成Input System UI Input Module这是新系统包自带的一个组件。实际操作在场景中找到 EventSystem 对象没有的话就创建一个空物体挂上EventSystem组件删除旧的Standalone Input Module添加UnityEngine.InputSystem.UI.InputSystemUIInputModule确保 UI 元素在正确的 EventSystem 下。这个坑非常常见。很多人装了新系统场景里的 EventSystem 还是旧的代码里没有报错但鼠标点击、键盘导航全部失效排查到最后才发现是组件不对。注意如果你的 EventSystem 上同时存在 Standalone Input Module 和新组件也是不行的。移除旧的只保留新的。6.3 生成了 C# 类但脚本里引用不到常见原因有三个勾选了Generate C# Class但没点Apply生成没有生效类名和项目里已有脚本重名改了命名空间但脚本里没有using对应的命名空间。解决方案是先检查生成出来的文件在哪里通常在资产同级目录。找不到就取消勾选重新勾选再 Apply 一次强制重新生成。类名冲突的话在 Inspector 里改一个不重复的类名再 Apply。6.4 手柄绑定无效或者只有键鼠能用先别怀疑代码多数是 Binding 配置的问题。打开资产编辑器双击对应动作确认手柄 Binding 确实存在Binding 的 Control Scheme 没有把 Gamepad 排除掉手柄在系统层能被识别。Windows 下如果手柄完全没事件先打开Window Analysis Input Debugger里面会列出当前所有已接入的输入设备及状态。如果 Input Debugger 里都看不到手柄那是操作系统层面的设备识别问题跟 Unity 无关。如果调试器里能看到手柄但动作不触发那大概率是 Binding 没配对。检查动作面板里的绑定树看有没有匹配到手柄的通道。6.5 多玩家场景下不同玩家互相抢输入本地多人游戏中两个玩家共用同一个动作资产会导致设备输入被抢。正确做法是用PlayerInput组件生成多个玩家实例并对每个实例做设备配对。常用接口playerInput.user.AssignDevice(device)把某个设备分配给指定玩家InputUser.PerformPairingDevice(device)把设备配对给某个用户。如果不用 PlayerInput就得自己写设备分发逻辑根据每个设备发出的输入判断该响应哪个玩家。这个逻辑本身不难但容易在边界情况上翻车比如一个玩家拔了手柄、另一个玩家插了新手柄状态错乱会非常头疼。7. 旧项目迁移与性能优化建议7.1 渐进式迁移先 Both 后 New我不建议把一个大型项目一次性切到新系统。比较稳的流程是这样的先把Active Input Handling设为Both让新旧代码共存新建.inputactions资产先把主角的核心动作移动、跳跃、交互配好用生成 C# 类的方式接入逐模块替换旧输入代码确认所有旧的Input.GetAxis、Input.GetKey调用清零后再把Active Input Handling切到 New。这个流程大概需要一到两周具体看项目规模。最痛苦的是旧插件和商店资源因为有些第三方资源内部用了旧 API在Both模式下不报错一旦切到 New 就会现原型。我建议在切换前全局搜索Input.Get、Input.mousePosition这类调用能改就改不能改的插件要考虑是否放弃。7.2 性能别在 Update 里轮询也别频繁 Enable / Disable前面已经强调过事件驱动优于每帧轮询。这里再补充一个点不要频繁在运行时创建InputAction对象也不要每帧反复调用 Enable 和 Disable。Enable/Disable 内部有状态注册和事件分发的开销。如果这个调用出现在每帧逻辑里会对性能产生明显影响。正确的做法是在状态切换时做整体的 Map 禁用/启用比如打开暂停菜单时一次性把GameplayMap 禁用关闭菜单时再启用。还有一些细节不要在Update里反复创建InputActionReference或者通过字符串查找动作使用生成类时动作实例已经固定开销是可控的ReadValueT()比事件回调更贵需要高频读取时尽量通过事件把值缓存下来。7.3 善用 Input Debugger 和重绑定 API开发阶段Window Analysis Input Debugger是排查输入问题的神器。它能列出所有已接入的设备、每个动作的当前状态、最近触发的事件。我看到它处理过的诡异问题包括手柄摇杆漂移、按键冲突、设备插拔后事件丢失等。玩家自定义键位功能新系统自带重绑定 APIvar rebindOperation moveAction.PerformInteractiveRebinding() .WithTargetBinding(bindingIndex) .Start();重绑定完成后把结果保存到 PlayerPrefs 或存档里下次启动时恢复。这套方案旧系统完全做不到也是新系统真正值得迁移的理由之一。我自己的项目里玩家改键功能就是靠这个 API 做的UI 上提示“按新按键”然后调用重绑定非常简单省掉了自己管理按键映射的整块逻辑。最后分享一点个人心得。从旧系统迁到新系统我前两周确实很难受整天在 Binding 里折腾觉得“为什么这么麻烦”。但等第一个项目跑顺之后后续所有输入相关工作都变得非常轻松玩家改键、手柄切换、多玩家配对全部从配置层和组件层解决代码里几乎不需要写映射逻辑。如果你正在一个新项目的起点别犹豫直接上 Input System如果你在维护老项目按第七节那个流程慢慢迁不要一步跨太大。最后记住一点遇到输入行为诡异先开 Input Debugger看设备有没有识别到、动作有没有触发再决定改代码还是改配置。这个习惯能帮你省下大量排查时间。