> ## 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 主机上的本地存储

> 本地存储

在 XBOX Series X|S 主机上可以访问四种本地存储：

* 临时本地存储
* 已安装游戏数据
* 开发者暂存分区
* 持久本地存储

| 存储类型 | 位置 |
| - | - |
| 已安装游戏数据 | G:\\ |
| 临时本地存储 | T:\\ |
| 开发者暂存分区 | D:\\ |
| 持久本地存储 | 调用 [XPersistentLocalStorageGetPathSize](/zh-CN/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetpathsize) 和 [XPersistentLocalStorageGetPath](/zh-CN/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetpath) 以获取路径大小和数据。 |
| 可下载内容 | 调用 [XPackageMount](/zh-CN/reference/system/xpackage/functions/xpackagemount) 挂载 DLC，调用 [XPackageGetMountPath](/zh-CN/reference/system/xpackage/functions/xpackagegetmountpath) 获取路径。 |

**XR-133：本地存储写入限制**

> [!NOTE]
>
> 运行在 XBOX Series S、XBOX Series X 或

其他同一主机家族的游戏，在 5 分钟滚动窗口内向持久本地存储 (PLS) 或临时本地存储写入的数据不得超过 1 GiB。超过 1GiB 写入的游戏无法通过认证测试。开发者可以查看 PIX 时序捕获中关于超过写入限制的警告。此外，游戏可以在运行时通过调用 [XPackageGetWriteStats](/zh-CN/reference/system/xpackage/functions/xpackagegetwritestats) 监视其写入统计信息。

**临时本地存储**
临时本地存储对游戏暴露为 *drive T*。游戏运行期间可以通过对任意 [XtfFileIO](/zh-CN/reference/tools/xtf/xtffileio/xtffileio-xbox-microsoft-n) 命令使用 */x:/title* 访问临时存储。临时本地存储允许存储和远程检索临时文件，例如日志文件。写入临时本地存储的文件仅保证在游戏运行期间可用。不保证写入 T: 驱动器的数据从一次游戏启动到下一次启动之间会被保留。游戏终止后，临时存储可能会在某个时点被删除。

临时本地存储还有以下特性：

* 2 GB 专用存储
* 游戏终止后内容会被删除。
* 在挂起和恢复（包括 quick resume）时内容会保留。

**已安装游戏数据**
当前运行游戏的已安装游戏数据的位置映射到 *drive G*。使用已打包构建时，此卷在运行中的游戏视图内为只读。

**开发者暂存分区**
开发者暂存分区暴露为 *drive D*。开发者暂存分区仅在开发期间用作本地存储。在零售模式下应编译时移除所有对其的引用，以免引发潜在问题。

**持久本地存储**
游戏可以在其清单中请求访问持久本地存储 (PLS)。

此存储空间旨在用作长期缓存，存储非游戏存档数据，例如回放和自定义渲染的游戏录像。PLS 不是为主要数据存储空间设计的。它绝不能用于游戏存档、内容更新或任何游戏运行所需的其他数据。相反，请使用 Connected Storage API 存储游戏存档，或对于仅在线游戏，可选择使用 XBOX 服务的 Title Storage 或发行商托管的云存储服务。

PLS 具有以下特性：

* 游戏专用：此存储空间只能由请求它的游戏访问。
* 主机专用：此存储空间始终创建在主机专用的 XVD 中（即使游戏安装在外部驱动器上），不能在其他主机上使用。
* 保证分配：系统会在允许游戏启动之前确保该空间已分配。如果硬盘可用空间不足，会提示用户释放空间以允许游戏运行。
* 用户可控：用户可以从系统 shell 中删除该存储空间。系统绝不会自动删除该空间中的任何项。
* 与游戏安装生命周期绑定：卸载游戏时，关联的本地存储空间也会被移除。如果重新安装游戏，之前存在的任何数据都不会恢复。
* 弹性强、防篡改：存储空间经过加密并进行完整性检查，因此游戏保存的数据无法被篡改。

要请求 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-CN/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetpathsize) 和 [XPersistentLocalStorageGetPath](/zh-CN/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetpath) 以获取路径大小和数据，后者返回该游戏持久存储的路径。可用总空间由游戏在 MicrosoftGame.config 中为本地存储所声明的值决定。

如果游戏通过内容更新增加其请求的持久本地存储空间大小，则升级过程中之前的存储空间会被删除，其内容会丢失。

**可共享的持久本地存储**

游戏可以选择将其持久本地存储以只读形式与其他游戏共享。允许某游戏读取另一游戏 PLS 的关系描述如下：

| 共享 PLS 的产品 | 可读取该 PLS 的产品 |
| - | - |
| 系列游戏中心 | 所有依赖此系列游戏中心的 hub 感知游戏，以及所有与该系列游戏中心存在 [RelatedProduct](/zh-CN/reference/system/microsoftgameconfig/elements/microsoftgameconfig-element-relatedproduct) 关系的游戏。 |
| Hub 感知游戏 | 关联的系列游戏中心以及所有与此游戏存在 [RelatedProduct](/zh-CN/reference/system/microsoftgameconfig/elements/microsoftgameconfig-element-relatedproduct) 关系的游戏。 |
| Hub 不感知游戏 | 所有与此游戏存在 [RelatedProduct](/zh-CN/reference/system/microsoftgameconfig/elements/microsoftgameconfig-element-relatedproduct) 关系的游戏。 |

要将 PLS 设为可共享，请在 MicrosoftGame.config 中作为 \<PersistentLocalStorage> 的子元素添加 \<Shareable> 标记。

```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 标记为可共享，那么在挂起游戏之前，

应确保关闭所有对该 PLS 的句柄；否则游戏挂起会失败并被终止。

**可增长的持久本地存储**
可增长的持久本地存储是 PLS 的扩展，允许游戏请求访问更大的本地存储空间，而无需预先永久保留该空间。它适用于某些场景需要额外空间但并非所有用户都会使用的游戏，例如用户生成内容 (UGC) 下载或大型本地回放文件。

要请求 Growable 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>
```

在写入 Growable PLS 之前，你的游戏必须使用 [XPersistentLocalStorageGetSpaceInfo](/zh-CN/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetspaceinfo) API 检查可用空间。请注意，调用 [GetDiskFreeSpaceExW](https://learn.microsoft.com/windows/win32/api/fileapi/nf-fileapi-getdiskfreespaceexw) 只会告诉游戏 PLS 中剩余的最大可用空间——但不保证这些空间可用。[XPersistentLocalStorageGetSpaceInfo](/zh-CN/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetspaceinfo) 还会返回总空闲空间以及实际可用空闲空间（PLS 空闲与底层驱动器实际空间中的较小者）。

如果你的游戏需要的空间超过当前可用，且尚未占满 Growable PLS 配额，但底层驱动器上没有足够空间供 PLS XVD 扩容，你需要通过 [XPersistentLocalStoragePromptUserForSpaceAsync](/zh-CN/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragepromptuserforspaceasync) 函数提示最终用户释放所需的额外空间。

如果游戏通过内容更新从使用不可增长的持久本地存储更改为可增长的存储空间，之前的存储空间在升级时将被删除，其内容会丢失。

**可下载内容**

可下载内容在安装后可以按需挂载和卸载。调用 [XPackageMount](/zh-CN/reference/system/xpackage/functions/xpackagemount) 挂载 DLC，调用 [XPackageGetMountPath](/zh-CN/reference/system/xpackage/functions/xpackagegetmountpath) 获取路径。

> [!NOTE]
>
> **绝不要**硬编码返回的路径值，因为它们可能随时间变化，并且仅在包挂载后才有效。

## 使用远程主机工具访问游戏数据

远程主机工具可以通过为 **/X** 开关指定 **/title** 使用与运行中的游戏相同的映射。这样远程主机工具就可以访问当前游戏写入到暂存卷的数据以及已安装的游戏数据。

要将暂存卷文件复制到你的开发 PC，请按如下方式使用 **xbcp**：

**xbcp /x:/title xd:\\***file-name* **c:\\***local-path*

要将文件从开发 PC 复制到游戏卷，请按如下方式使用 **xbcp**：

**xbcp /x:/title c:\\***file-name* **xg:\\***dest-path*

只有在游戏运行时你才能从开发 PC 访问 PLS。可以使用 xb 命令在此位置往返复制文件。例如：

**xbcp /x:/title c:\\***file-name* **xr:\\***dest-path*

有关使用远程主机工具处理主机上文件的语法的更多信息，请参阅 [文件复制 (xbcp.exe) (NDA 主题)](/zh-CN/tools/tools-console/commandlinetools/xbcp)。

## 参考 API 文档

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

## 另请参阅

[游戏存档概述](/zh-CN/build/core-features/common/game-save/game-saves-overview)
[系列游戏中心](https://learn.microsoft.com/gaming/gdk/docs/store/franchise-game-hubs)


## Related topics

- [游戏存档存储系统](/zh-CN/build/core-features/common/game-save/game-saves-storage-systems.md)
- [XPackageGetWriteStats](/zh-CN/reference/system/xpackage/functions/xpackagegetwritestats.md)
- [XPersistentLocalStoragePromptUserForSpaceAsync](/zh-CN/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragepromptuserforspaceasync.md)
- [XPersistentLocalStorageGetSpaceInfo](/zh-CN/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetspaceinfo.md)
- [XPackageGetMountPath](/zh-CN/reference/system/xpackage/functions/xpackagegetmountpath.md)