问题排查

先查看 Manager 显示的消息，以及最新一轮 Runner 日志。保存配置、Runner 就绪、游戏启动和 Steam 状态属于不同阶段；先确定哪一步失败，再调整相关设置。

预期的完整流程见开始使用。

Manager 无法打开

确认已经完整解压 WinUI 预览版，并在 Windows 11 24H2 x64 的普通文件资源管理器中运行 SteamWrapper.Manager.exe。

不要从 ZIP 内启动，也不要把 EXE 与 DLL、原生资源、Assets、Runner 和语言资源分开。旧 SteamWrapperManager.exe 属于已退役实现；测试证据产物也不是 WinUI 应用。

如果存在，可以查看：

%LOCALAPPDATA%\SteamWrapper\logs\manager-startup.log

自包含目录包含运行时文件，但干净系统验收和新的 WinUI 安装器尚未完成。请重新解压完整产物，不要把不同版本的包拼在同一个目录里。详见安装指南。

没有找到 Steam 游戏或安装位置

在 ＋ 添加游戏 中选择实际 Steam 文件夹，或者手动填写原游戏的 AppID。发现功能读取本机安装 manifest，不会在线查询你的账号，也不会修复 Steam 文件。

Steam 安装位置 显示无法确认，可能是发现失败，也可能是同一 AppID 对应多个安装目录。这不会使你独立选择的 实际运行文件夹 失效，也不应把它替换为猜测的官方路径。

已有配置时应打开该配置。同一 AppID 对应多份配置的冲突，需要先解决，才能生成明确的命令。

游戏显示占位，没有显示封面

这不表示游戏或配置已经损坏。Manager 先读取自定义 Steam 图片与本地库缓存，支持新的哈希目录；跳过空文件、被占用、不可读或无效的图片。如果希望 Steam 自己填充正常图片缓存，可以在 Steam 中打开该游戏的库页面，再重新打开添加 Steam 游戏。

从 Steam 下载缺失封面默认关闭。只有希望发送官方图片请求时才在该对话框中开启。关闭时，以前下载且有效的封面仍可显示；清除已下载封面只删除 SteamWrapper 的副本，不改变自定义图片或 Steam 文件。详见封面设置。

部分 Steam 图片没有可用的 AppID 固定竖图地址。离线、超时、404／限流响应或图片损坏时也会保留占位，并短暂抑制重复失败请求；选择、保存和启动仍可使用。不要仅为修复封面而运行 Steam 完整性校验或替换游戏文件。

Manager 拒绝保存配置

检查错误指出的字段：

• AppID 必须是有效的正整数 Steam AppID。
• 游戏名称、实际运行文件夹和目标程序不能为空。
• 实际运行文件夹必须存在，并且是完整路径。
• WinUI 的目标程序必须是现有 .exe。
• 明确填写的工作目录，在解析相对路径后必须存在。
• 按进程名等待时必须填写进程名称。

如果 Manager 报告文件已经被外部修改，先保留尚未保存的值，再使用 重新读取配置。重新读取或放弃会有意丢弃当前编辑，不要只是为了消除冲突就覆盖外部版本。

对于不支持的配置版本、字段值或内联/点号 TOML 表布局，编辑器无法安全保存时会保持原文件不变。明确属于其他平台的配置在 WinUI 中只读。这些情况都不意味着需要删除整个配置文件。

配置已经保存，但 Runner 尚未就绪

保存配置可以在 Runner 安装或校验失败前成功完成。应根据具体 Runner 消息处理，不能仅因为配置保存成功，就认为启动项已经可用。

消息或症状	下一步
随包文件或清单无法通过校验	重新解压完整且匹配的预览包
Runner 文件仍在使用	正常退出游戏和启动器，再重试保存
已安装版本未知，或同版本内容不同	保留现有文件，使用匹配的包；不要删除元数据来强行替换
已保留较新的兼容 Runner	这是预期的防降级行为
无法确认共享位置	按下一节说明，从普通文件资源管理器重新打开 Manager

WinUI 在保存配置时准备并检查稳定 Runner。

Manager 提示从文件资源管理器重新打开

某些开发环境或带包身份的宿主环境，可能把字面上的 AppData 路径重定向到私有文件视图。该视图中存在文件，并不能证明普通 Steam 能访问它。

关闭 Manager，通过普通 Windows 文件资源管理器打开完整预览目录，再双击 Manager 并重新保存配置。使用新生成命令中的稳定共享 Runner 路径。

不要把宿主的私有缓存路径填写到 Steam 启动项中来绕过警告。应用会在报告 Runner 就绪前检查文件句柄的最终位置。

Steam 没有启动所选游戏

先将 Steam 中保存的启动选项与 Manager 生成的完整文本比较：

"<stable-runner-path>" --appid "<appid>" -- %command%

检查 AppID 是否一致、稳定 Runner 路径是否带引号、-- 分隔符与末尾 %command% 是否完整。不要指向 Manager 或包内自带的 Runner 副本。

然后检查配置中的实际运行文件夹、目标和工作目录。游戏移动后，即使重新选了 EXE，配置仍可能保留旧目录。相对路径都会基于实际运行文件夹解析。

查看本轮会话对应的日志：

%LOCALAPPDATA%\SteamWrapper\logs\runner-<appid>.log

Runner 没有界面，失败时可能不会弹出错误窗口。日志记录配置加载、启动的 profile、提供时的 Steam 原始展开命令，以及错误或报告的退出状态。日志会跨会话追加，请查看最新条目。

当前 Runner 启动的是配置中的目标和参数。它会接收原始 Steam 命令，但不会与目标同时执行该命令，也不会自动转发其中的参数。程序需要的参数应填写在 profile 中。

打开了错误语言，或游戏提示缺少资源

确认 要运行的程序 是汉化版真正需要的入口。同一个目录里可能同时包含原版 EXE 与汉化启动器。应检查完整资源和工作目录，而不只是文件名。

进行直接启动对照时，请在普通文件资源管理器中进入游戏目录内部，双击与配置完全相同的 EXE。在资源管理器仍停留于父目录时，输入绝对程序路径启动，并不是等价的工作环境检查。

如果完整版本直接启动也失败，修改 SteamWrapper 的等待模式不能修复缺失资源。在从合法来源获取匹配的完整版本前，先保留当前文件与存档。

官方与汉化副本应独立存放。Steam 的更新或完整性校验可能替换官方安装目录中已修改的文件；不要把修复或校验尚未保护的混合目录作为第一步排错。详见汉化游戏与存档保护。

Steam 过早停止，或一直显示运行中

如果启动器拉起的游戏还开着，Steam 就停止显示运行中，应检查等待模式。旧配置可能仍使用只等待直接启动器的 root；新 Windows 配置使用 job。

如果游戏窗口关闭后 Steam 仍在运行，启动器或辅助进程可能尚未退出。先识别该进程，尽量使用正常退出操作。按进程名等待还可能包含启动后出现的无关同名进程。

修改设置前请阅读等待模式。可见窗口、进程父子关系或启动器退出码，本身都不能证明 Job 成员关系或实际游戏的退出状态。

存档、云同步或成就不符合预期

Steam 报告云存档冲突时应停止操作。先确定哪些进度属于你打算使用的版本，再选择要保留的副本。

SteamWrapper 不会自动备份游戏存档、在版本之间迁移存档、修改 Steam Cloud 规则，也不会补上缺失的成就逻辑。修改实际运行文件夹后，可能会使用不同的本地存档位置。

成功启动、时长增加或 Overlay 正常，都不能证明成就兼容。正常解锁条件和游戏的 Steam 集成都需要实际工作。短暂进入标题、未达到解锁条件的测试，不应被当成成就失败。详见汉化游戏。

语言切换失败，或重开后没有保留

请使用侧栏选择器。成功切换会刷新应用自有界面，并单独保存到：

%LOCALAPPDATA%\SteamWrapper\ui-settings.json

没有已保存的 language 键时，Manager 跟随已支持的系统界面语言，不支持时使用英语。已保存的手动选择优先，明确的未知值或无法读取的设置回退英语。Manager 使用 en-US 与 zh-CN；修改偏好不会改变 profiles、用户填写的文字或日志内容。

如果文件损坏、含重复键、超过支持的大小/深度，或无法安全写入，Manager 会报告问题并保留原文件。写入失败时保留之前的界面语言。手工修复设置文件前先留一份副本，不要为了重置语言而删除 profiles.toml。

系统 picker 自有文案和外部原始诊断可能使用 Windows 或系统语言。已经保存的游戏名称和参数值则有意不参与翻译。

提交有用的问题报告

提供 Manager 类型与代码版本、Windows 版本、AppID、所选目标、实际运行/工作目录、等待模式、能否直接启动，以及相关的最新日志。说明问题出现在标题前、游玩中，还是正常退出后。

分享前检查路径和日志，其中可能包含用户名与原始启动参数。默认不要附带凭据、完整 Steam 账号配置、游戏文件或存档。

如果需要撤销测试，恢复配置前保留的 Steam 启动选项。游戏自然更新的存档应继续保留，除非另有明确的恢复方案。