> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # XBOX PC Remote 工具常见问题解答和故障排除指南 > XBOX PC Remote 工具常见问题的解答和故障排除指导。 # XBOX PC Remote 工具常见问题解答和故障排除指南 XBOX PC Toolbox 应用处于预览阶段。请从 Windows 上的 [Microsoft Store](https://aka.ms/toolboxinstaller) 下载。 ## 常见问题 | 问题 | | --------------------------------------------------------------------------------- | | [有哪些已知问题、依赖项和限制?]() | | [Fully Managed 和 Lightweight 设备类型有什么区别?]() | | [在哪里可以找到应用版本号?]() | | [从开发 PC 取消配对是否会完全断开设备的连接?]() | | [如何查找目标设备的设备连接信息?]() | | [如何验证设备中的配置更改?]() | | [如何验证和更改沙盒?]() | | [如何为安全通道设置选择特定的网络适配器?]() | | [如何报告问题?]() | | [XBOX Device Management PowerShell Module (XDM) 与 wdRemote/wdEndpoint 有什么区别?]() | | [我同时需要 XBOX Device Management PowerShell Module (XDM) 和 wdRemote/wdEndpoint 吗?]() | | [为什么第一次要以管理员身份运行 wdEndpoint?]() | | [我可以将多个游戏部署到同一目标设备吗?]() | | [如果在部署过程中网络连接断开会发生什么?]() | | [所有通信都加密吗?]() | | [我应该为每项任务使用哪个工具?]() | | [这些工具可以用于任何 Windows 游戏吗?]() | | [这些工具使用什么网络端口?]() | ### Fully Managed 和 Lightweight 设备类型有什么区别? **如果你需要管理设备配置、远程运行 PowerShell 命令或使用 DSC 保持设备处于一致状态,请选择 Fully Managed**。SSH 在设置期间会自动为你安装和配置。 **如果你只需要在目标设备上部署、启动和终止游戏,并且希望在没有 SSH 的情况下更快地进行设置,请选择 Lightweight**。 两种设备类型都使用加密通信。Fully Managed 使用 SSH 进行加密,而 Lightweight 使用 HTTPS/TLS。你为开发 PC 选择的设备类型必须与目标设备上的设备类型匹配。例如,你不能在目标设备上选择 Lightweight,而在开发 PC 上选择 Fully Managed。 | | Fully Managed | Lightweight | | -------- | ---------------------------- | ---------------- | | **加密** | SSH | HTTPS/TLS | | **最适合** | 完整的设备管理和远程迭代 | 仅用于部署、启动和终止的快速设置 | | **协议** | 通过 SSH 的 PowerShell 远程处理 | HTTPS/TLS | | **设置** | 自动安装并配置 SSH;需要接受指纹 | 无需 SSH 设置,配置更快 | | **远程迭代** | 部署、启动和终止 | 部署、启动和终止 | | **设备管理** | DSC 配置、沙盒管理和 PowerShell 远程处理 | 不可用 | ### 在哪里可以找到应用版本号? 应用版本号显示在 XBOX PC Toolbox 应用的左上角。你也可以在 **设置** 菜单中找到它。 ### 有哪些已知问题、依赖项和限制? #### 已知问题 1. PowerShell/DSC 设置可能失败,且 XBOX PC Toolbox 在设置期间可能意外关闭。 * **解决方法:** 请参阅 [PowerShell 和 DSC 预配在设置期间失败](#powershell-and-dsc-provisioning-fails-during-setup)。 2. 已加入域的目标设备:在 Fully Managed 模式下,OpenSSH 连接仅支持基于密码的身份验证(首选基于密钥的身份验证,但不可用)。Lightweight 预配可作为已加入域设备的替代方案。 * **注意**:此问题影响使用 Fully Managed 模式的已加入域的 Windows Pro 设备。团队正在与 OpenSSH 和 Microsoft Entra ID 团队合作以进行未来改进。 3. WinGet 命令错误(例如,`winget search` 失败) * **解决方法:** 重新启动目标设备。产品团队正在调查此问题。 4. Visual Studio 调试器性能:XBOX PC Remote Debugger 尚未针对性能进行优化。预计调试时间比本地调试要慢。将来的版本会改善调试器性能。 5. XBOX PC Remote Debugger 在几次调试迭代后可能会停止响应。在大约 50 次迭代后重新启动目标设备。 * **解决方法:** 重新启动目标设备,然后重新启动调试器会话。 #### 依赖项和限制 * 两台设备在设置期间都需要 Internet 访问。 * 设备必须位于同一本地网络上,并且能够互相 ping 通。 * XBOX PC Toolbox 应用仅在 RETAIL 沙盒中可用。请确保设备处于 RETAIL 模式,才能从 Microsoft Store 下载。 * 受支持的设备:Windows 10 或 Windows 11,家庭版或专业版。 * 设置期间需要对两台设备的物理访问。 * 设置期间需要两台设备的管理员访问权限。 * 已加入 Microsoft Entra ID 的目标设备仅通过 Lightweight 预配支持。Fully Managed 不适用于加入了 Entra 的设备。应用会自动检测到这一点,并在设置期间禁用 Fully Managed 选项。 ### 从开发 PC 取消配对是否会完全断开设备的连接? 不会。从开发 PC 取消配对只会将设备从你的本地工作区中移除。它不会清除远程目标设备上的 SSH 密钥。若要完全断开连接,请从 **远程目标设备** 取消配对。此操作会移除两台设备上的 SSH 密钥,并确保干净地断开连接。 ### 如何查找设备连接信息? 将目标设备与 XBOX PC Toolbox 配对后,连接详细信息会显示在 **测试设备** 屏幕上。 设备工作区连接详细信息 或者,在目标设备上使用 PowerShell。 ```powershell theme={null} # 打开一个 PowerShell 7 终端 $env:ComputerName # 设备名称 $env:Username # 用户名 ipconfig # IP 地址 ``` ### 如何验证设备上的配置更改? 使用设备状态配置 (DSC) 和 PowerShell 测试配置。 ```powershell theme={null} # 在 DevPC 上打开一个 PowerShell 7 终端 dsc config test -f "$env:LOCALAPPDATA\XboxPCDeviceManager\config\devPC.dsc.yaml" # 网络(可在任一设备上使用) dsc config test -f "$env:LOCALAPPDATA\XboxPCDeviceManager\config\network.dsc.yaml" ``` ```powershell theme={null} # 在 TargetDevice 上打开一个 PowerShell 7 终端 dsc config test -f "$env:LOCALAPPDATA\XboxPCDeviceManager\config\targetDevice.dsc.yaml" ``` 你也可以在 Windows 设置中检查每台设备的配置更改。 ### 如何验证和更改沙盒? 为了工具正常工作,请将你的沙盒设置为 **RETAIL**。要检查当前配置,请运行:`xblpcsandbox /get` 如果配置未设置为 **RETAIL**,请运行以下命令进行切换: `XblPCSandbox.exe RETAIL` ### 如何为安全通道设置选择特定的网络适配器? 在设置期间,XBOX PC Toolbox 允许你选择网络适配器。 网络适配器选择屏幕 ### 如何报告问题? 从 XBOX PC Toolbox 标题栏中,选择 **发送反馈**。然后选择 **报告问题**。 alt text 请包含以下详细信息: * **操作系统** 版本 (Windows 10/11 版本) * 对于 XBOX Device Management PowerShell Module 问题,请提供 **PowerShell 版本** (`$PSVersionTable`) * **网络配置** (Wi-Fi/以太网、公司/家庭) * **错误消息**(确切文本) * **重现步骤** * 你使用的是 **哪个工具**(XBOX PC Toolbox、XBOX Device Management PowerShell Module、`wdRemote` 或 `wdEndpoint`) * **预览版本** ### XBOX Device Management PowerShell Module (XDM) 与 `wdRemote/wdEndpoint` 有什么区别? * **XDM**:设置安全通信通道。 * **`wdRemote/wdEndpoint`**:通过这些通道部署和启动游戏。 ### 我同时需要 XDM 和 `wdRemote/wdEndpoint` 吗? 是。使用 XDM 建立连接,然后使用 `wdRemote/wdEndpoint` 进行游戏部署和执行。 ### 为什么第一次要以管理员身份运行 `wdEndpoint`? 第一次运行 `wdEndpoint` 时,你需要管理员访问权限来创建和存储证书并绑定 HTTPS URL。后续运行不需要提升。 ### 我可以将多个游戏部署到同一目标设备吗? 是。将游戏部署到不同的目录,并根据需要启动它们。 ### 如果在部署过程中网络连接断开会发生什么? `wdRemote` 会显示错误。恢复连接后,重新尝试部署命令。 ### 所有通信都加密吗? 是。开发 PC 与目标设备之间的所有通信都经过加密。 ### 我应该为每项任务使用哪个工具? * **XBOX PC Toolbox**:使用它来远程预配和获取设备、设置安全通道、安装依赖项以及配置设备。 * **测试连接**:在部署游戏之前使用 XBOX PC Toolbox。 * **远程会话**:使用启用了 XDM 的远程会话和 PowerShell 远程处理在目标设备上执行命令。 * **`wdRemote/wdEndpoint`**:使用这些工具来部署、测试和终止游戏。 ### 这些工具可以用于任何 Windows 游戏吗? 是。这些工具适用于任何 Windows 可执行文件,而不仅仅是 Microsoft 游戏开发工具包 (GDK) 游戏。 ### 这些工具使用什么网络端口? * **XDM**:SSH(端口 22) * **`wdEndpoint`**:HTTPS(端口 4275) *** ## 故障排除指南 ### 在公司网络环境中配对失败 如果你在公司网络上,并且设备无法配对或通信: * 验证两台设备在网络上是否彼此可见。公司防火墙或网络分段可能会阻止设备到设备的通信。 * 确保设备之间开放了以下端口:**端口 22**(OpenSSH)和 **端口 4275**(Remote Iteration 工具)。 * 在尝试配对或连接之前断开任何 VPN 连接。 * 如果你的组织需要设备注册,请根据你的 IT 策略确认你的设备已注册。 ### 安装所需工具时出错 如果在安装 XBOX PC Device Manager、Microsoft.PowerShell.\* 或 Microsoft.Windows.Developer 模块时收到错误: * **解决方法**:从 `%onedrive%/Documents/PowerShell/Modules/` 中删除模块目录并重试。 * **原因**:OneDrive 可能会干扰 PowerShell 模块的安装。 ### PowerShell 和 DSC 预配在设置期间失败 如果在安装 PowerShell/DSC 组件时设置失败,或者 XBOX PC Toolbox 在设置期间关闭: * 打开提升的终端并运行: ```powershell theme={null} winget uninstall Microsoft.PowerShell winget uninstall Microsoft.DSC winget install Microsoft.PowerShell --installer-type wix winget install Microsoft.DSC --installer-type zip ``` * 如果在这些步骤后安装 DSC 时挂起,请重新启动 XBOX PC Toolbox 并重试。 ### OpenSSH 错误:kex\_exchange\_identification: read: Connection reset * 重新启动目标设备。 * 确保设备位于专用网络配置文件上;否则,防火墙可能会阻止连接。 * 检查本地设备上是否有损坏的 `known_hosts` 文件。 这是与 XBOX PC Toolbox 应用无关的 OpenSSH 特定问题。 ### winget Microsoft PowerShell 7.5 安装失败 (0x8A150049) * **解决方法**:卸载 PowerShell 7.6(Visual Studio 2026 附带)。较新版本会导致安装冲突。 ### 配对后通过 SSH 运行 winget 失败 如果通过 **Connect** 配对设备后 `winget` 命令失败: * **解决方法**:在目标设备上运行 `Repair-WinGetPackageManager`,或重新启动目标设备。 * **原因**:此问题发生在 SSH 连接上。 ### 掌上设备上的游戏部署失败 如果掌上设备在部署期间进入睡眠状态,导致游戏部署失败: * **解决方法**:调整目标设备的电源设置,防止其在部署期间进入睡眠状态。请确保在部署期间将设备的睡眠计时器设置为较长的持续时间或禁用它。 * **原因**:XBOX PC Toolbox 不再通过 DSC 管理设备电源设置。在具有激进睡眠计时器的掌上设备上,设备在部署过程中进入睡眠状态,导致 `wdRemote` 失败。 ### 配对在远程目标设备上显示成功,但开发 PC 上的 SSH 连接失败 如果远程目标设备显示配对成功,但开发 PC 未能完成 SSH 设置,请检查以下内容: **验证远程目标设备上的 OpenSSH 服务器是否正在运行:** ```powershell theme={null} Get-Service sshd ``` 如果服务已停止,请重新启动它: ```powershell theme={null} Restart-Service sshd ``` 如果服务未运行,则开发 PC 无法与远程目标设备建立 SSH 连接。 **检查开发 PC 上的 ssh-agent 是否提供陈旧的密钥:** 通过绕过 ssh-agent 进行测试: ```powershell theme={null} ssh -o IdentitiesOnly=yes -i "$env:USERPROFILE\.ssh\XboxPCDeviceManagerKey" -o PreferredAuthentications=publickey user@target-ip "echo SUCCESS" ``` * 如果此命令 **成功**,则 ssh-agent 正在缓存错误的密钥。按照以下步骤修复。 * 如果此命令 **失败**,则问题出在远程目标设备端。要进一步诊断,请参阅 [如何收集 OpenSSH 日志]()。 要修复 ssh-agent: ```powershell theme={null} # 清除所有缓存的密钥 ssh-add -D # 重启代理服务 Restart-Service ssh-agent # 仅重新添加正确的密钥 ssh-add "$env:USERPROFILE\.ssh\XboxPCDeviceManagerKey" # 验证仅加载了你的密钥 ssh-add -l # 测试连接 ssh -o PreferredAuthentications=publickey user@target-ip "echo SUCCESS" ``` ### 如何收集 OpenSSH 日志 如果遇到与 OpenSSH 相关的连接问题,请启用详细日志记录以帮助诊断问题。 1. 以管理员身份打开 **记事本**。 2. 打开文件 `C:\ProgramData\ssh\sshd_config`。 如果该文件未出现在记事本中,请将文件筛选器从 **文本文档 (\*.txt)** 更改为 **所有文件 (*.*)**。 3. 找到以 `# Logging` 开头的部分,并将: ```text theme={null} # Logging #SyslogFacility AUTH #LogLevel INFO ``` 更改为: ```text theme={null} # Logging SyslogFacility LOCAL0 LogLevel Debug3 ``` 4. 以管理员身份打开 PowerShell 终端并重新启动 SSH 服务: ```powershell theme={null} net stop sshd net start sshd ``` 5. 在 XBOX PC Toolbox 应用中重现该问题。 6. 从 `C:\ProgramData\ssh\logs` 收集日志。将该文件夹压缩为 .zip 文件以与开发团队共享。 7. 收集日志后,还原在步骤 3 中所做的更改(在每行的开头重新添加 `#`),并再次使用步骤 4 重新启动 SSH 服务。 ## 另请参阅 * [如何使用 XBOX PC Remote 工具](/tools/tools-pc/xbox-pc-remote-tools/how-to-use-tools) * [XBOX PC Remote 工具快速入门指南](/tools/tools-pc/xbox-pc-remote-tools/quickstart) * [XBOX PC Remote 工具概述](/tools/tools-pc/xbox-pc-remote-tools) ## Related topics - [XBOX PC Remote 工具:2026 年 3 月 (2603) 发行说明](/zh-CN/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603.md) - [如何使用 XBOX PC Remote 工具](/zh-CN/tools/tools-pc/xbox-pc-remote-tools/how-to-use-tools.md) - [多人游戏常见问题和故障排除](/zh-CN/services/xbox-services/multiplayer/mpsd/concepts/live-multiplayer-2015-faq.md) - [XBOX PC Remote 工具快速入门指南](/zh-CN/tools/tools-pc/xbox-pc-remote-tools/quickstart.md) - [XBOX PC Remote Tools](/zh-CN/tools/tools-pc/xbox-pc-remote-tools/index.md)