8. 疑难解答与常见问题

这里是最常见的问题，按新用户通常遇到它们的顺序排列。如果你的问题不在这里，请查阅服务参考——每个服务都有自己的页面，其中包含“注意事项”（Gotchas）小节（同样的页面也随包发布在你项目的 Documentation/Modules/ 下）——或者联系我们（见 8.9 节）。

8.1 “我导入了包，但场景里什么都没出现”

这是有意的设计。框架是代码，不是场景对象——没有需要摆放的预制体，也没有需要配置的管理器。你按下 Play 的那一刻它就会自行启动。想看到它在工作：

• 打开 Welcome 窗口：Tools > Common Game System > Welcome（也在 Window > Common Game System > Welcome 下）。它在导入后会自动打开一次，之后两个菜单项随时都能把它调出来。
• 点击该窗口顶部的 Open Demo Scene 并按下 Play。Motion Lab 演示会实时展示补间、定时器和不受暂停影响的时钟系统，无需任何设置。
• 或者干脆在任意场景中按下 Play，然后在 Console 中查找 bootstrap complete (v2.1.0, 23 services) 这一行。

8.2 “编辑器提示要为新 Input System 重启”

选“是”。当项目首次启用 Input System 包时，Unity 会弹出这个提示——输入后端只能在重启期间切换。重启不会动到你的项目和这个包。之后，Welcome 窗口仍可以从上面列出的两个菜单打开，一切从你离开的地方继续。

8.3 “演示场景或示例不响应我的鼠标和键盘”（在控制台里按 Enter 没有反应）

你的项目仍停留在旧的输入后端上。安装 Input System 包并不会切换后端，新建项目会一直停在 “Input Manager (Old)” 上——因此演示场景、UI 示例和命令控制台会悄无声息地收不到任何输入。

修复只需一次点击：只要存在这种情况，Welcome 窗口就会显示黄色警告和一个 Enable the new Input System (restarts the editor) 按钮。点击它，让编辑器重启，然后再次按下 Play。如需改为手动操作：Edit > Project Settings > Player > Other Settings > Active Input Handling → “Input System Package (New)” 或 “Both”，然后重启编辑器。

重启是必需的，不是可选项：即使设置已经更改，正在运行的编辑器会话仍可能停留在旧后端上。如果输入看起来仍然失灵，在调试任何其他东西之前先重启编辑器。

8.4 “找不到演示场景”

Motion Lab 演示的按钮和滑块需要 Unity 内置的 uGUI 包（com.unity.ugui）。如果该包已从项目中移除，演示的脚本会把自己排除在编译之外，场景因此无法运行。从 Package Manager 重新安装 uGUI，演示就会回来。无论哪种情况，框架本身都不受影响——没有 uGUI 它照样启动并运行所有服务（见第 7.2 章）。

8.5 “存档在编辑器里正常，但 IL2CPP 构建会丢存档”

你的存档类在构建时被剥离了。IL2CPP 会移除看起来未被使用的类，而只为序列化而存在的类恰好就是这副模样。在 Assets/ 下添加一个 link.xml 文件，列出你的存档数据类——完整配方（附可复制粘贴的文件）在第 6.3 章。同样的修复也适用于自定义设置组。

8.6 “那 2,600+ 个自动化测试在哪里？”

有意隐藏了。这套 2,600+ 个自动化测试随包一起发布，但放在 Unity 不会导入的文件夹里，因此它永远不会给你的项目增加编译时间或杂乱。想亲自运行：打开 Welcome 窗口，点击底栏的 Import framework tests。测试随后会出现在 Unity 的 Test Runner 中（Window > General > Test Runner）。这完全是可选的——套件在发布前已经全部通过。完整流程见第 3.4 章。

8.7 “它兼容 URP、HDRP 或内置渲染管线吗？”

三者都兼容。框架不绘制任何内容，也不包含任何着色器、材质或渲染管线代码。它提供的是逻辑：存档、计时、事件、输入路由、音频混音以及其他服务。渲染你游戏的是什么，对它来说完全不可见，因此管线升级永远不会波及框架。

8.8 “控制台报错：Unknown action map 'ui.panel'”

UI 面板栈试图启用它的菜单输入映射，但你的输入资产中没有定义它们。在你的 .inputactions 资产中添加两个名称严格为 ui.panel 和 ui.modal 的动作映射（小写、带点），并按照第 6.2 章所示接入该资产。

8.9 获取帮助

• 邮箱：yoop80075@gmail.com —— 请附上你的 Unity 版本，如果有的话，再附上 Console 中以 bootstrap complete 开头的那一行。
• **本手册：**随包发布于 Documentation/CGS-Manual.pdf，在线版本从快速上手开始。
• **服务参考：**每个服务一页通俗易懂的说明——在线见文档索引，或在你的项目中的 Documentation/Modules/ 下（例如 Modules/SaveLoad.md）——各自包含完整 API、一个可运行示例和已知注意事项。
• **更新日志：**包根目录的 CHANGELOG.md 列出了每个版本的变更。
• **快捷链接：**Welcome 窗口的链接行（Manual、Documentation、Changelog、Module Reference）可直接打开上述所有内容。