> ## 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 One 主機上可存取四種類型的本機儲存空間：

* 暫存本機儲存空間
* 已安裝的遊戲資料
* 開發人員暫存分割區
* 永續性本機儲存空間

| 儲存空間類型 | 位置 |
| - | - |
| 已安裝的遊戲資料 | G:\\ |
| 暫存本機儲存空間 | T:\\ |
| 開發人員暫存分割區 | D:\\ |
| 永續性本機儲存空間 | 呼叫 [XPersistentLocalStorageGetPathSize](/zh-TW/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetpathsize) 和 [XPersistentLocalStorageGetPath](/zh-TW/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetpath) 以取得路徑大小和資料。 |
| 可下載內容 | 呼叫 [XPackageMount](/zh-TW/reference/system/xpackage/functions/xpackagemount) 以掛接 DLC，並呼叫 [XPackageGetMountPath](/zh-TW/reference/system/xpackage/functions/xpackagegetmountpath) 以取得路徑。 |

**XR-133：本機儲存空間寫入限制**

<Note>
  在 XBOX Series S、XBOX Series X 或任何
</Note>

同一主機系列中的其他主機上執行的遊戲，在任何連續 5 分鐘的期間內，寫入
永續性本機儲存空間 (PLS) 或暫存本機儲存空間的資料均不得超過 1 GiB。寫入量
超過 1GiB 的遊戲將無法順利通過認證測試。開發人員可以查看
PIX 計時擷取中的警告，以了解何時超過寫入限制。此外，遊戲也可以
在執行階段呼叫 [XPackageGetWriteStats](/zh-TW/reference/system/xpackage/functions/xpackagegetwritestats) 來監視其寫入統計資料。

**暫存本機儲存空間**
暫存本機儲存空間會以 *T 磁碟機* 的形式公開給遊戲。在遊戲執行期間，可對任何 [XtfFileIO](/zh-TW/reference/tools/xtf/xtffileio/xtffileio-xbox-microsoft-n)
命令使用 */x:/title* 來存取暫存儲存空間。暫存本機儲存空間可讓您儲存和遠端擷取暫存檔案，例如
記錄檔。寫入暫存本機儲存空間的檔案，僅保證在遊戲
執行期間可供使用。不保證寫入 T: 磁碟機的資料在每次遊戲啟動之間
都會保留。暫存儲存空間可能會在遊戲
終止後的某個時間點遭到刪除。

暫存本機儲存空間也具有下列功能：

* 2 GB 的專用儲存空間
* 遊戲終止後，內容會遭到刪除。
* 暫停和繼續 (包括 Quick Resume) 時，內容會保留。

**已安裝的遊戲資料**
目前執行中遊戲的已安裝遊戲資料位置會對應至
*G 磁碟機*。使用封裝組建時，此磁碟區在執行中遊戲的檢視內為唯讀。

**開發人員暫存分割區**
開發人員暫存分割區會以 *D 磁碟機* 的形式公開。開發人員暫存
分割區是僅供開發期間使用的本機儲存空間。您應該在零售模式中將所有對它的參考
排除在編譯之外，以避免任何潛在問題。

**永續性本機儲存空間**
遊戲可以在其資訊清單中要求存取永續性本機儲存空間 (PLS)。

此儲存空間的用途是作為長期快取，以儲存非遊戲存檔資料，例如
重播和自訂轉譯的遊戲錄製內容。PLS 並非設計為主要資料
儲存空間。絕不可將其用於遊戲存檔、內容更新，或遊戲執行時
必須存在的任何其他資料。請改為使用 Connected Storage API 儲存遊戲存檔；或者，
對於僅限線上的遊戲，也可選擇使用 XBOX services Title Storage 或發行者裝載的雲端儲存
服務。

PLS 具有下列特性：

* 遊戲專屬：此儲存空間只能由要求它的遊戲存取。
* 主機專屬：此儲存空間一律建立在主機專屬的 XVD 中
  (即使遊戲安裝在外接磁碟機上也一樣)，且無法在其他
  主機上使用。
* 保證配置：系統會確保在允許遊戲啟動之前配置空間。
  如果可用的硬碟空間不足，系統會提示使用者釋放
  空間以讓遊戲執行。
* 由使用者控制：使用者可以從系統殼層刪除此儲存空間。系統
  絕不會自動刪除空間中的任何項目。
* 與遊戲安裝的存續期間綁定：解除安裝遊戲時，相關聯的本機儲存
  空間也會一併移除。如果重新安裝遊戲，先前存在的資料都不會
  還原。
* 具復原能力且防竄改：此儲存空間經過加密並進行完整性檢查，因此
  遊戲儲存的資料無法遭到竄改。

若要要求 PLS，請將下列標記新增至 MicrosoftGame.config，作為 \<Game> 的子項。

```xml theme={null}
<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">
    <!-- snip -->
    <PersistentLocalStorage><SizeMB>1024</SizeMB></PersistentLocalStorage>
</Game>
```

若要取得本機永續性儲存空間，請呼叫 [XPersistentLocalStorageGetPathSize](/zh-TW/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetpathsize)
和 [XPersistentLocalStorageGetPath](/zh-TW/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetpath) 以取得路徑大小和資料，這會傳回遊戲的
永續性儲存空間路徑。可用空間總量取決於
遊戲在 MicrosoftGame.config 的本機儲存空間宣告中所要求的量。

如果遊戲使用內容更新來增加其所要求的永續性本機儲存
空間大小，則在升級期間，先前的儲存空間將會遭到刪除，其內容也會遺失。

**可共用的永續性本機儲存空間**

遊戲可以選擇以唯讀方式與其他遊戲共用其永續性本機儲存空間。允許遊戲讀取另一個遊戲 PLS 的關聯性說明如下：

| 共用 PLS 的產品 | 讀取可共用 PLS 的產品 |
| - | - |
| 系列遊戲中心 | 所有相依於此系列遊戲中心的中心感知遊戲，以及所有與此系列遊戲中心具有 [RelatedProduct](/zh-TW/reference/system/microsoftgameconfig/elements/microsoftgameconfig-element-relatedproduct) 關聯性的遊戲。 |
| 中心感知遊戲 | 相關聯的系列遊戲中心，以及所有與此遊戲具有 [RelatedProduct](/zh-TW/reference/system/microsoftgameconfig/elements/microsoftgameconfig-element-relatedproduct) 關聯性的遊戲。 |
| 非中心感知遊戲 | 所有與此遊戲具有 [RelatedProduct](/zh-TW/reference/system/microsoftgameconfig/elements/microsoftgameconfig-element-relatedproduct) 關聯性的遊戲。 |

若要讓 PLS 可共用，請將標記 \<Shareable> 新增至 MicrosoftGame.config，作為 \<PersistentLocalStorage> 的子項。

```xml theme={null}
<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">
    <!-- snip -->
    <PersistentLocalStorage>
        <Shareable>true</Shareable> <!--This is optional, and the default value is false -->
    </PersistentLocalStorage>
</Game>
```

<Note>
  如果遊戲將其 PLS 標示為可共用，則應確保在暫停遊戲之前，
</Note>

關閉其 PLS 的所有控制代碼，否則遊戲暫停將會失敗，且遊戲將會遭到終止。

**可成長的永續性本機儲存空間**
可成長的永續性本機儲存空間是 PLS 的延伸，可讓遊戲要求存取
大得多的本機儲存空間，而不需預先永久保留該空間。它
適合某些情境需要額外空間的遊戲使用，例如
使用者產生內容 (UGC) 下載或大型本機重播檔案，而這些情境並非所有使用者都會
用到。

若要要求可成長的 PLS，請將下列標記新增至 MicrosoftGame.config，作為 \<Game> 的子項。

```xml theme={null}
<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">
    <!-- snip -->
    <PersistentLocalStorage>
        <!-- <SizeMB>1024</SizeMB>   --Optional.  To be used if your title always wants 1024 MBs pre-allocated even before launch -->
        <GrowableToMB>20480</GrowableToMB> <!-- This is not a static reservation, but the largest size your title PLS can grow to -->
    </PersistentLocalStorage>
</Game>
```

在寫入可成長的 PLS 之前，您的遊戲必須使用
[XPersistentLocalStorageGetSpaceInfo](/zh-TW/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetspaceinfo) API 檢查可用空間。請注意，
呼叫
[GetDiskFreeSpaceExW ](https://learn.microsoft.com/windows/win32/api/fileapi/nf-fileapi-getdiskfreespaceexw)
只會告訴遊戲 PLS 中剩餘的最大可用空間，這並不保證
可供使用。
[XPersistentLocalStorageGetSpaceInfo](/zh-TW/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetspaceinfo) 也會傳回
可用空間總計以及實際可用空間 (即可用空間與基礎磁碟機上實際
空間兩者中的最小值)。

如果您的遊戲需要的空間超過可用空間，且尚未用滿其可成長的 PLS 配置，但
磁碟機上的基礎空間不足以增加 PLS XVD，您就必須使用
[XPersistentLocalStoragePromptUserForSpaceAsync](/zh-TW/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragepromptuserforspaceasync)
函式，提示使用者釋放您的遊戲所需的額外空間。

如果遊戲使用內容更新，從使用不可成長的永續性本機儲存空間變更為
可成長的儲存空間，則在升級期間，先前的儲存空間將會遭到刪除，其內容也會
遺失。

**可下載內容**

可下載內容在安裝之後，可以視需要掛接和卸載。呼叫
[XPackageMount](/zh-TW/reference/system/xpackage/functions/xpackagemount) 以掛接 DLC，並呼叫 [XPackageGetMountPath](/zh-TW/reference/system/xpackage/functions/xpackagegetmountpath)
以取得路徑。

<Note>
  **絕不可**將傳回的路徑值硬式編碼，因為這些值可能會隨時間而變化，且僅在套件掛接之後才有效。
</Note>

<a id="ID4EFCAC" />

## 使用遠端主機工具存取遊戲資料

遠端主機工具可以搭配 **/X** 參數指定 **/title**，以使用與執行中遊戲相同的
對應。接著，遠端主機工具即可存取寫入暫存磁碟區的資料，以及
目前遊戲的已安裝遊戲資料。

若要將暫存磁碟區檔案複製到您的開發電腦，請依下列方式使用 **xbcp**：

<strong>xbcp /x:/title xd:\\</strong><em>file-name</em> <strong>c:\\</strong><em>local-path</em>

若要將檔案從您的開發電腦複製到遊戲磁碟區，請依下列方式使用 **xbcp**：

<strong>xbcp /x:/title c:\\</strong><em>file-name</em> <strong>xg:\\</strong><em>dest-path</em>

只有在遊戲執行時，您才能從開發電腦存取 PLS。可以使用 xb 命令將檔案複製到
此位置或從此位置複製檔案。例如：

<strong>xbcp /x:/title c:\\</strong><em>file-name</em> <strong>xr:\\</strong><em>dest-path</em>

如需使用遠端主機工具處理主機上檔案之語法的詳細資訊，
請參閱[檔案複製 (xbcp.exe) (NDA 主題)](/zh-TW/tools/tools-console/commandlinetools/xbcp)。

<a id="ID4ELEAC" />

## 參考 API 文件

* [XPackage (API 內容)](/zh-TW/reference/system/xpackage/xpackage_members)
  * 函式
    * [XPackageMount](/zh-TW/reference/system/xpackage/functions/xpackagemount)
    * [XPackageGetMountPath](/zh-TW/reference/system/xpackage/functions/xpackagegetmountpath)
    * [XPackageGetWriteStats](/zh-TW/reference/system/xpackage/functions/xpackagegetwritestats)
* [xpersistentlocalstorage (API 內容)](/zh-TW/reference/system/xpersistentlocalstorage/xpersistentlocalstorage_members)
  * 函式
    * [XPersistentLocalStorageGetPathSize](/zh-TW/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetpathsize)
    * [XPersistentLocalStorageGetPath](/zh-TW/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetpath)
    * [XPersistentLocalStorageGetSpaceInfo](/zh-TW/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetspaceinfo)
    * [XPersistentLocalStoragePromptUserForSpaceAsync](/zh-TW/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragepromptuserforspaceasync)

## 另請參閱

[遊戲存檔概觀](/zh-TW/build/core-features/common/game-save/game-saves-overview)
[系列遊戲中心](https://learn.microsoft.com/gaming/gdk/docs/store/franchise-game-hubs)


## Related topics

- [XBOX 主機遊戲的認證測試 XBOX 需求](/zh-TW/publishing/certification/console-cert-tested-requirements.md)
- [XR-052 使用者狀態與遊戲存檔位置、漫遊及相依性](/zh-TW/publishing/certification/xr/xr-052.md)
- [XR-018：使用者產生的內容](/zh-TW/publishing/certification/xr/xr-018.md)
- [XR-048 設定檔設定的使用](/zh-TW/publishing/certification/xr/xr-048.md)
- [XBOX 遊戲的 XBOX 需求](/zh-TW/publishing/certification/xbox-requirements.md)