> ## 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.

# Economy 第 2 版 (V2) 常見問題集

> XBOX PC 遠端工具常見問題的解答與疑難排解指引。

# XBOX PC 遠端工具常見問題集與疑難排解指南

> [!NOTE]
>
> XBOX PC Toolbox 應用程式目前為預覽版。請從 Windows 上的 [Microsoft Store](https://aka.ms/toolboxinstaller) 下載。

## 常見問題集

| 問題 |
| - |
| [有哪些已知問題、相依性與限制？]() |
| [Fully Managed 與 Lightweight 裝置類型有何差異？]() |
| [在哪裡可以找到應用程式版本號碼？]() |
| [從開發電腦取消配對是否會完全中斷裝置連線？]() |
| [如何找到目標裝置的裝置連線資訊？]() |
| [如何驗證裝置中的設定變更？]() |
| [如何驗證與變更沙箱？]() |
| [如何為安全通道設定選取特定的網路介面卡？]() |
| [如何回報問題？]() |
| [XBOX Device Management PowerShell 模組 (XDM) 與 wdRemote/wdEndpoint 有何差異？]() |
| [我需要同時使用 XBOX Device Management PowerShell 模組 (XDM) 與 wdRemote/wdEndpoint 嗎？]() |
| [為什麼第一次要以系統管理員身分執行 wdEndpoint？]() |
| [可以將多個遊戲部署至同一部目標裝置嗎？]() |
| [如果部署期間網路連線中斷會發生什麼情況？]() |
| [所有通訊都會加密嗎？]() |
| [哪項工作應該使用哪個工具？]() |
| [這些工具可以用於任何 Windows 遊戲嗎？]() |
| [這些工具使用哪些網路連接埠？]() |

### Fully Managed 與 Lightweight 裝置類型有何差異？

如果您需要管理裝置設定、從遠端執行 PowerShell 命令，或使用 DSC 讓裝置保持一致的狀態，請**選取 Fully Managed**。設定期間會自動為您安裝並設定 SSH。

如果您只需要在目標裝置上部署、啟動與終止遊戲，並希望在沒有 SSH 的情況下更快完成設定，請**選取 Lightweight**。

兩種裝置類型都使用加密通訊。Fully Managed 使用 SSH 加密，而 Lightweight 使用 HTTPS/TLS。您為開發電腦選取的裝置類型必須與目標裝置上的裝置類型相符。例如，您不能在目標裝置上選取 Lightweight，而在開發電腦上選取 Fully Managed。

| | Fully Managed | Lightweight |
| - | - | - |
| **加密** | SSH | HTTPS/TLS |
| **最適合** | 完整裝置管理與遠端反覆開發 | 僅需部署、啟動與終止的快速設定 |
| **通訊協定** | 透過 SSH 的 PowerShell 遠端處理 | HTTPS/TLS |
| **設定** | 自動安裝並設定 SSH；需要接受指紋 | 不需設定 SSH，佈建速度較快 |
| **遠端反覆開發** | 部署、啟動與終止 | 部署、啟動與終止 |
| **裝置管理** | DSC 設定、沙箱管理與 PowerShell 遠端處理 | 無法使用 |

### 在哪裡可以找到應用程式版本號碼？

應用程式版本號碼顯示在 XBOX PC Toolbox 應用程式的左上角。您也可以在 **Settings** 功能表中找到。

### 有哪些已知問題、相依性與限制？

#### 已知問題

1. PowerShell/DSC 設定可能會失敗，且 XBOX PC Toolbox 可能會在設定期間意外關閉。
   * **因應措施：** 請參閱 [PowerShell 與 DSC 佈建在設定期間失敗](#powershell-and-dsc-provisioning-fails-during-setup)。
2. 已加入網域的目標裝置：在 Fully Managed 模式下，OpenSSH 連線僅支援密碼型驗證 (建議使用金鑰型驗證，但目前無法使用)。對於已加入網域的裝置，可改用 Lightweight 佈建。
   * **注意**：此問題會影響使用 Fully Managed 模式且已加入網域的 Windows 專業版裝置。小組正與 OpenSSH 及 Microsoft Entra ID 小組合作，以在未來進行改進。
3. WinGet 命令錯誤 (例如 `winget search` 失敗)
   * **因應措施：** 重新開機目標裝置。產品小組正在調查此問題。
4. Visual Studio 偵錯工具效能：XBOX PC Remote Debugger 尚未針對效能進行最佳化。與本機偵錯相比，偵錯時間預期會較慢。未來的版本將會改善偵錯工具效能。
5. XBOX PC Remote Debugger 在多次偵錯反覆執行後可能會停止回應。請在大約 50 次反覆執行後重新啟動目標裝置。
   * **因應措施：** 重新啟動目標裝置，然後重新啟動偵錯工作階段。

#### 相依性與限制

* 兩部裝置在設定期間都需要網際網路存取。
* 裝置必須位於相同的區域網路，且能夠互相 ping。
* XBOX PC Toolbox 應用程式僅在 RETAIL 沙箱中提供。請確定裝置處於 RETAIL 模式，才能從 Microsoft Store 下載。
* 支援的裝置：Windows 10 或 Windows 11 家用版或專業版。
* 設定期間需要能實際操作兩部裝置。
* 設定時，兩部裝置都需要系統管理員存取權。
* 已加入 Microsoft Entra ID 的目標裝置僅透過 Lightweight 佈建提供支援。已加入 Entra 的裝置無法使用 Fully Managed。應用程式會自動偵測此狀況，並在設定期間停用 Fully Managed 選項。

### 從開發電腦取消配對是否會完全中斷裝置連線？

不會。從開發電腦取消配對只會從本機工作區移除裝置，不會清除遠端目標裝置上的 SSH 金鑰。若要完全中斷連線，請從**遠端目標裝置**取消配對。此動作會移除兩部裝置上的 SSH 金鑰，並確保乾淨地中斷連線。

### 如何找到裝置連線資訊？

將目標裝置與 XBOX PC Toolbox 配對之後，連線詳細資料會顯示在 **Testing Device** 畫面上。

![裝置工作區連線詳細資料](https://mintcdn.com/microsoft-4404708b/N3T1ucKV7zIMBudj/images/remote-win-gamedev/test_device_connection_details_1.png?fit=max\&auto=format\&n=N3T1ucKV7zIMBudj\&q=85\&s=74271b29b9f9cbcb86c4463c1ea915e3)

或者，在目標裝置上使用 PowerShell。

```powershell theme={null}
# Open a PowerShell 7 terminal
$env:ComputerName  # Device name
$env:Username      # Username  
ipconfig           # IP address
```

### 如何驗證裝置上的設定變更？

使用 Device State Configuration (DSC) 與 PowerShell 測試設定。

```powershell theme={null}
# Open a PowerShell 7 terminal on the DevPC
dsc config test -f "$env:LOCALAPPDATA\XboxPCDeviceManager\config\devPC.dsc.yaml"

# Network (usable on either device)  
dsc config test -f "$env:LOCALAPPDATA\XboxPCDeviceManager\config\network.dsc.yaml"
```

```powershell theme={null}
# Open a PowerShell 7 terminal on TargetDevice
dsc config test -f "$env:LOCALAPPDATA\XboxPCDeviceManager\config\targetDevice.dsc.yaml"
```

您也可以在每部裝置的 Windows 設定中檢查設定變更。

### 如何驗證與變更沙箱？

請將沙箱設為 **RETAIL** 以使用工具功能。若要檢查目前的設定，請執行：`xblpcsandbox /get`

如果設定不是 **RETAIL**，請執行下列命令進行切換：

`XblPCSandbox.exe RETAIL`

### 如何為安全通道設定選取特定的網路介面卡？

設定期間，XBOX PC Toolbox 可讓您選取網路介面卡。

![網路介面卡選取畫面](https://mintcdn.com/microsoft-4404708b/N3T1ucKV7zIMBudj/images/remote-win-gamedev/netadapterselection.png?fit=max\&auto=format\&n=N3T1ucKV7zIMBudj\&q=85\&s=4070a24507303c19e2768195b2af9aa7)

### 如何回報問題？

從 XBOX PC Toolbox 標題列選取 **Send Feedback**。然後選取 **Report a Problem**。

![alt text](https://mintcdn.com/microsoft-4404708b/iADzli99B7EWodAv/images/xboxpctoolbox/feedback-icon.png?fit=max\&auto=format\&n=iADzli99B7EWodAv\&q=85\&s=899b38220aba876e2f157f3c280152aa)

請包含下列詳細資料：

* **作業系統**版本 (Windows 10/11 組建)
* **PowerShell 版本** (`$PSVersionTable`)，適用於 XBOX Device Management PowerShell 模組問題
* **網路設定** (Wi-Fi/乙太網路、公司/家用)
* **錯誤訊息** (確切文字)
* **重現步驟**
* 您使用的**工具** (XBOX PC Toolbox、XBOX Device Management PowerShell 模組、`wdRemote` 或 `wdEndpoint`)
* **預覽版本**

### XBOX Device Management PowerShell 模組 (XDM) 與 `wdRemote/wdEndpoint` 有何差異？

* **XDM**：設定安全通訊通道。
* **`wdRemote/wdEndpoint`**：透過這些通道部署與啟動遊戲。

### 我需要同時使用 XDM 與 `wdRemote/wdEndpoint` 嗎？

是的。使用 XDM 建立連線，然後使用 `wdRemote/wdEndpoint` 進行遊戲部署與執行。

### 為什麼第一次要以系統管理員身分執行 `wdEndpoint`？

第一次執行 `wdEndpoint` 時，您需要系統管理員存取權才能建立與儲存憑證，並繫結 HTTPS URL。後續執行不需要提高權限。

### 可以將多個遊戲部署至同一部目標裝置嗎？

可以。將遊戲部署至不同的目錄，並視需要啟動它們。

### 如果部署期間網路連線中斷會發生什麼情況？

`wdRemote` 會顯示錯誤。恢復連線後，請重試部署命令。

### 所有通訊都會加密嗎？

是的。開發電腦與目標裝置之間的所有通訊都會加密。

### 每項工作應該使用哪個工具？

* **XBOX PC Toolbox**：用於遠端佈建與取得裝置、設定安全通道、安裝相依性以及設定裝置。
* **測試連線**：在部署遊戲之前使用 XBOX PC Toolbox。
* **遠端工作階段**：使用啟用 XDM 的遠端工作階段與 PowerShell 遠端處理，在目標裝置上執行命令。
* **`wdRemote/wdEndpoint`**：使用這些工具部署、測試與終止遊戲。

### 這些工具可以用於任何 Windows 遊戲嗎？

可以。這些工具適用於任何 Windows 可執行檔，而不僅限於 Microsoft Game Development Kit (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` 檔案是否損毀。

> [!NOTE]
>
> 這是 OpenSSH 特有的問題，與 XBOX PC Toolbox 應用程式無關。

### winget Microsoft PowerShell 7.5 安裝失敗 (0x8A150049)

* **因應措施**：解除安裝 PowerShell 7.6 (隨附於 Visual Studio 2026)。較新的版本會造成安裝衝突。

### 配對後透過 SSH 執行 winget 失敗

如果在使用 **Connect** 配對裝置後 `winget` 命令失敗：

* **因應措施**：在目標裝置上執行 `Repair-WinGetPackageManager`，或重新開機目標裝置。
* **原因**：此問題會在 SSH 連線上發生。

### 在掌機裝置上部署遊戲失敗

如果在部署期間進入睡眠的掌機裝置上部署遊戲失敗：

* **因應措施**：調整目標裝置上的電源設定，防止裝置在部署期間進入睡眠。部署時，請確定裝置的睡眠計時器設定為較長的時間或已停用。
* **原因**：XBOX PC Toolbox 不再透過 DSC 管理裝置電源設定。在睡眠計時器較積極的掌機裝置上，裝置會在部署途中進入睡眠，導致 `wdRemote` 失敗。

### 遠端目標裝置上顯示配對成功，但開發電腦上的 SSH 連線失敗

如果遠端目標裝置顯示配對成功，但開發電腦無法完成 SSH 設定，請檢查下列項目：

**確認 OpenSSH 伺服器正在遠端目標裝置上執行：**

```powershell theme={null}
Get-Service sshd
```

如果服務已停止，請重新啟動：

```powershell theme={null}
Restart-Service sshd
```

如果服務未執行，開發電腦就無法與遠端目標裝置建立 SSH 連線。

**檢查開發電腦上的 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}
# Clear all cached keys
ssh-add -D

# Restart the agent service
Restart-Service ssh-agent

# Re-add only the correct key
ssh-add "$env:USERPROFILE\.ssh\XboxPCDeviceManagerKey"

# Verify only your key is loaded
ssh-add -l

# Test the connection
ssh -o PreferredAuthentications=publickey user@target-ip "echo SUCCESS"
```

### 如何收集 OpenSSH 記錄

如果您遇到與 OpenSSH 相關的連線問題，請啟用詳細資訊記錄以協助診斷問題。

1. 以系統管理員身分開啟 **記事本**。
2. 開啟檔案 `C:\ProgramData\ssh\sshd_config`。

> [!NOTE]
>
> 如果檔案未出現在記事本中，請將檔案篩選條件從 **文字文件 (\*.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 遠端工具](/zh-TW/tools/tools-pc/xbox-pc-remote-tools/how-to-use-tools)
* [XBOX PC 遠端工具快速入門指南](/zh-TW/tools/tools-pc/xbox-pc-remote-tools/quickstart)
* [XBOX PC 遠端工具概觀](/zh-TW/tools/tools-pc/xbox-pc-remote-tools)


## Related topics

- [Economy 第 2 版 (V2) 常見問題集](/zh-TW/services/playfab/economy-monetization/economy-v2/faq.md)
- [Economy v2 概觀](/zh-TW/services/playfab/economy-monetization/economy-v2/overview.md)
- [GameInput 常見問題集](/zh-TW/build/core-features/common/input/overviews/input-faq.md)
- [XBOX Game Publisher Insights 常見問題集](/zh-TW/publishing/game-publishing/concepts/game-publisher-insights/game-publisher-insights-faq.md)
- [PC 開發人員常見問題集](/zh-TW/build/gdk-and-engines/guides/pc-faq.md)