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

# 游戏打包、更新与流式安装测试

> 游戏打包、内容更新和流式安装测试

本文介绍如何在整个开发生命周期中为流式安装创建包,包括本地迭代、性能验证、提交前测试和最终提交。文中描述了 MakePkg 工具在打包时运行的步骤,并概述了开发过程中打包和测试流式安装的推荐做法。

## 引言

[MakePkg.exe](/build/core-features/common/packaging/deployment/makepkg) 是一个将内容放入二进制打包文件的工具,该文件被称为 XBOX Virtual Container(XVC)。主机的包扩展名为 .xvc,PC 的包扩展名为 .msixvc。除扩展名的差异外,还会在包名中添加后缀以区分 XBOX One Family(\_x)和 XBOX Series X|S Family(\_xs)包。

MakePkg.exe 将你的游戏内容和一个映射文件作为输入,生成使用众所周知的测试密钥、随机生成的密钥或安全的稳定密钥加密的包。用于加密的密钥取决于该包是用于本地测试还是提交给 Microsoft 用于发布。以下部分详细介绍各用例。

[映射文件](/build/core-features/common/packaging/deployment/atoc-deployment-schema) 中的 XML 有两个作用。首先,它指定游戏在运行时可用的文件位置。其次,它指定每个文件所属的区块文件。一组区块 —— 称为 *启动集(launch set)* —— 总是在允许游戏运行之前被安装。其余区块会在游戏运行时安装。可以通过 API 查询区块安装的进度,并修改尚未安装的区块的安装顺序。

本文包含:

* [打包过程中的步骤](#steps_during_packaging)
* [开发期间打包的推荐步骤](#recommended_steps_for_packaging_during_development)
* [流式安装包的测试](#testing_of_streaming_installation_packages)
* [最佳实践](#best_practices)
* [由打开的数据连接导致的打包失败](#open-data-connections)
* [资源与指导](#resources_and_guidance)
* [另请参见](#see_also)

<a id="steps_during_packaging" />

## 打包过程中的步骤

MakePkg 打包过程包含若干步骤。

### MicrosoftGame.config 和文件存在性验证

`makepkg` 命令会检查内容源目录中的 [MicrosoftGame.config](/build/core-features/common/game-config/MicrosoftGameConfig-Overview) 文件是否有效并可安装。

当你运行 `makepkg pack` 命令时,它会确保 MicrosoftGame.config 中引用的文件都位于源目录中。它会验证这些文件是否已作为启动集的一部分包含在包中。此验证包括二进制文件、图像文件以及任何其他资源。

### 二进制签名

XBOX Code Integrity(XCI)会扫描并签名你游戏中的文件。作为此过程的一部分,它会在将文件写入包文件之前修改文件中检测到的 PE 头。如果签名失败,会报告一条错误消息。该消息包含一条命令,用于手动重新运行 xcihash.exe 以收集有关签名失败的更多详情。

### 包创建

一旦 MakePkg 完成预验证步骤,它就会创建包文件。然后 MakePkg 会按照 XML 映射文件指定的区块,将源文件(包括已签名的可执行文件)复制到包文件中。

<Note>仅主机:包创建的最后一步涉及嵌入一个 Game OS 文件(GameOs.xvd)。此文件是 Microsoft 游戏开发工具包(GDK)的一部分,必须与游戏可执行文件一起放在布局目录中。`/gameos` 标志用于指定 Game OS 文件的替代源位置。</Note>

### 加密

| 类型                  | Test Signing (**/lt**) | Random Key (**/l**) | Stable Key (**/lk SECRET.LEKB**) |
| ------------------- | ---------------------- | ------------------- | -------------------------------- |
| 差异上传                | 是                      | 否                   | 是                                |
| packageutil compare | 是                      | 否                   | 是                                |
| 安全上传                | 否                      | 是                   | 是                                |
| 存储时安全               | 否                      | 是                   | 是                                |
| 在开发套件上侧载            | 是                      | 否                   | 是                                |
| 在 PC 上侧载            | 是                      | 否                   | 否                                |

#### 测试签名(默认加密)

MakePkg 的默认行为是创建测试签名的包,也可以在调用 `makepkg pack` 时通过 `/lt` 开关显式指定。测试签名使用众所周知的测试加密密钥加密所生成的包文件,旨在用于性能测试验证,可在 XBOX 和 PC 上运行。虽然实时包解密的效果被设计为对游戏透明,但这一测试可确保任何由于加密而可能出现的性能问题在游戏认证和最终发布之前被发现。测试签名的包不用于对内容进行加密保护,因为其加密使用固定密钥。测试签名的包可以使用 **xbapp install** 安装到开发套件,或使用 **wdapp install** 安装到开发 PC。

#### 随机密钥加密(`/l` 开关)

MakePkg 的 `/l` 开关使用随机生成的加密密钥加密包文件。除了你的游戏包之外,MakePkg `/l` 还会输出一个名称形如 *PackageFullName\_licenseName\_GUID.EKB* 的文件。(注意使用下划线(\_)字符。)使用 `/l` 开关创建的包无法安装到开发套件或开发 PC 上。你应使用测试签名的包测试游戏,直到游戏通过所有检查和提交前测试。达到该状态后,再在最终向 Microsoft 提交之前使用 `/l` 开关运行 MakePkg。

#### 推荐 - 稳定密钥加密(Genkey + /lk 开关)

Makepkg 的 `/lk` 开关使用由 `makepkg genkey` 命令生成的稳定(始终相同)密钥加密包。除了游戏包之外,`makepkg /lk` 还会输出名称形如 *PackageFullName\_licenseName\_GUID.EKB* 和 *PackageFullName\_licenseName\_GUID.CEKB* 的文件。(注意使用下划线(\_)字符。)使用 `/lk` 开关创建的包可以安装到开发套件上,但不能安装到开发 PC 上。对于 PC,你应使用测试签名的包测试游戏,直到游戏通过所有检查和提交前测试。

这是开发套件测试和提交时推荐的加密模式,原因如下:

1. packageutil compare 可以生成正确的更新大小估算(与 /l 不同)。
2. 使用与主机和 PC 下载内容更新相同的算法,支持安全差异上传到 Partner Center。
3. 可以安装到开发套件上(与 `/l` 不同)。
4. 使用安全的加密密钥材料,且只能在特定环境中解密(与 `/lt` 不同)。

与 `/lt` 和 `/l` 加密模式不同,`/lk` 模式使用需要一个一次性的额外步骤:

1. 一次性:运行 `makepkg genkey /ekb SECRET_KEY.lekb` 来创建 SECRET\_KEY.lekb 文件。这是 Local Escrowed Key Blob (LEKB),
   其中存储着加密你包的稳定内容密钥。它应存储在一个仅供必要人员访问的安全位置。理想情况下,
   只有官方的构建机器/账户才能访问它。
2. 包创建:运行 `makepkg pack /lk SECRET_KEY.lekb ...`。这会创建一个使用存储在 SECRET\_KEY.lekb 文件中的密钥加密的包。
3. 包上传:XVC 和 EKB 文件像往常一样上传到 Partner Center。LEKB 和 CEKB 文件不进行上传。

`xbapp install` 会自动安装将包加载到 XBOX 开发套件所需的 CEKB 文件。如果你正在测试非工具安装以外的场景
(游戏光盘、外部存储、主机间传输),请使用 `xbapp installkey` 命令仅安装 CEKB 文件。

<Warning>LEKB 文件的内容仅进行了轻度混淆。你有责任通过限制对 LEKB 文件的访问来确保你的内容包的安全性。任何拥有 LEKB 文件和 `makepkg pack` 输出的内容包文件的人</Warning>
都可以解密其内容。

<Warning>CEKB 文件的内容允许在任何激活的 XBOX 开发套件上加载该包。你有责任通过限制对 CEKB 文件的访问来确保你的内容包的安全性。任何拥有 CEKB 文件、激活的 XBOX 开发套件以及 `makepkg pack` 输出的内容包文件的人</Warning>
可以在他们的开发套件上安装该包、启动该包,并使用 xbcp 从包中提取文件。

### 提交验证

MakePkg 会在创建包后自动对游戏文件运行 [Submission Validator (SubmissionValidator.dll)](/build/core-features/common/packaging/subval/submissionvalidator)。Submission Validator 的目标是检查可能导致游戏在 Microsoft 的摄取、提交或认证过程中,或在将来的内容更新中出现问题的错误和问题。你需要在生成用于上传到 Partner Center 的签名包之前,更正所有检测到的问题。

提交验证过程会生成一个 XML 日志文件,详细说明任何失败的性质和位置。此过程会将此日志文件写入 MakePkg 的 `/pd` 参数为包文件输出所指定的相同位置。此日志可以包含失败或警告。你必须在能够将包提交给 Microsoft 之前解决失败问题。考虑修正警告,以确保游戏符合政策和 XBOX Requirements(XR)指导。

当你将包上传到 Partner Center 并将其提交至摄取流程时,验证检查会再次运行。此过程可确保使用最新版本的 Submission Validator 检查游戏,并尽早发现任何问题。

#### 提交验证测试

| 提交和验证测试                  | 说明                                                                                                 |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| **外来文件**                 | 验证游戏中不包含禁止文件。禁止文件包括源代码和调试文件(例如 \*.c、\*.cpp、\*.obj、\*.lib、\*.cs 和 \*.h),以及 Game OS 卷中包含的任何系统文件。     |
| **MicrosoftGame.config** | MakePkg 未执行的各种配置检查:徽标和启动画面图像的分辨率与位深。检查包是否正确支持模组(仅 PC 桌面)。                                          |
| **二进制扫描**                | 扫描所有 .exe 和 .dll 文件是否有任何非零售依赖项。任何托管代码二进制文件都会导致失败(仅主机)。其他检测到的问题包括非 XBOX 可执行文件(仅主机)和 32 位可执行文件(仅主机)。 |

具体测试会随着 Microsoft 识别出新问题而随时间演变。通过 Submission Validator 检查不应被视为其他问题不会在摄取和认证过程中出现的迹象。相反,其意图仅仅是减少由于可预见的错误导致被拒的时间和成本。此外,尽管 Submission Validator 可以检查某些与安全相关的问题,但不应将其视为对游戏的安全测试。

你可以从 XBOX Game Developer(XGD)站点下载最新版本的 Submission Validator。由于该工具的演进节奏可能与 XBOX One Software Development Kit 的发布不同,请确保使用最新版本,以避免在提交过程中出现验证失败的被拒。要获取最新版本,请参见 [XBOX Developer Downloads->XBOX One->Submission Validator](https://aka.ms/gdkdl)。

有关 Submission Validator 的详细信息,请参见 GDK 文档中的 [Submission Validator (SubmissionValidator.dll)](/build/core-features/common/packaging/subval/submissionvalidator)。

如果你对验证过程有疑问,请联系你的 Microsoft 客户代表。

<a id="recommended_steps_for_packaging_during_development" />

## 开发期间打包的推荐步骤

要在开发期间创建包,请使用以下步骤。以 PC 为目标时,使用 `wdapp` 代替 `xbapp`。

1. 使用测试签名的包和来自你开发 PC 的 **xbapp install** 在本地迭代。

   **MakePkg.exe pack /f** *Mapfile* **/d** *LooseContentDir* **/pd** *OutputFolder*

   入门指南请参见 [XBOX Developer Downloads](https://aka.ms/xgddl)。

2. 通过从 shell 启动或使用 **xbapp launch** 运行游戏。

   **xbapp install** *local-XVC-path* 或 **xbapp install** *http-URI*

   要测试其他流式安装选项,请参见本文后面的 [测试流式安装包](#testing-streaming-installation-packages-console)。

3. 使用刻录到蓝光光盘根目录的测试签名包,从光驱测试游戏安装。将光盘插入 XBOX 开发套件后,运行以下命令。

   **xbapp install** XO:\\*XVC-file-name*

4. 使用与测试签名包相同的打包命令,并添加 `/l` 标志,准备你的最终提交。

<a id="testing_of_streaming_installation_packages" />

## 测试流式安装包(PC)

使用 `wdapp` 命令在测试 PC 上安装包。

<Note>目前,测试用的 MSIXVC 包必须位于测试 PC 上的物理驱动器或 Web 服务器上。在未来的更新中会增加对通用命名约定(UNC)共享安装的支持。</Note>

有关详细信息,请参见 [PC 打包入门](/build/core-features/common/packaging/overviews/packaging-getting-started-for-PC)。

## 测试流式安装包(主机)

你可以以四种方式测试测试签名流式安装包的安装。

### 从开发 PC 流式传输

从开发 PC 流式传输不支持任何吞吐节流。安装速度取决于你开发 PC 的处理器和 I/O 特性,以及开发 PC 与开发套件之间的网络连接带宽。你可以预期在使用机械硬盘的现代开发 PC 通过千兆以太网连接的情况下达到 300 Mbps(约 36 MiB/s)或更高的速度。

**xbapp install** *dev-pc-path-to-XVC*

[通过命令行安装](/tools/tools-console/commandlinetools/xbapp#xbapp-install)

[通过 XBOX Manager 安装](/tools/tools-console/xbom/manager-tool-managing-applications#deploying-apps)

### 将包托管在 Web 服务器上

如果你的 Web 服务器支持带宽节流配置,将包托管在 Web 服务器上可以模拟不同的网络交付速度。XBOX One 平台会处理连接失败和重试逻辑。除了速度之外,你的游戏在从互联网源安装时的行为应与从光盘安装时相同。

**xbapp install** *http-URI-to-package*

[通过命令行安装](/tools/tools-console/commandlinetools/xbapp#xbapp-install)

[通过 XBOX Manager 安装](/tools/tools-console/xbom/manager-tool-managing-applications#deploying-apps)

### 将包刻录到光盘,然后从命令行安装

将 XVC 刻录到光盘的根目录,然后使用以下命令安装包。

**xbapp install** XO:\\*XVC-file-name*

### 将包刻录到光盘,然后通过 shell 安装

将包放入一个名为 MSXC 的文件夹并刻录到光盘中。

将光盘插入正在运行的开发套件。shell 会自动开始安装你的游戏,并在启动集安装完成后,开发套件会显示通知,此时可以启动游戏。

<a id="best_practices" />

## 最佳实践

### 使用子文件内容更新

使用子文件内容更新,可以减小内容更新的体积。编写你的包布局以确保在未来获得最佳的内容更新效率。

有关为最佳更新而编写包的更多信息,请参见 [内容更新最佳实践](/build/core-features/common/packaging/packaging-updates)。

### XBOX Requirement 034(XR-034:Streaming Install Initial Play Marker)

包含初始玩家标记是可选的,但强烈建议使用。它允许玩家在游戏完全安装之前运行游戏,而安装在后台继续。根据 [XR-034](https://learn.microsoft.com/build/store/policies/Console/certification-requirements#content-packages-and-updates):Streaming Install Initial Player Marker,包含 Initial Play Marker 的游戏在从 initial play marker 启动时必须提供一次游玩体验。

### 测试你的游戏

在从各种来源以不同速度进行安装时测试你的游戏。

### 使用最新的 Submission Validator

始终使用最新版本的 Submission Validator。

Submission Validator 的最新版本可从 [XBOX Developer Downloads->XBOX One->Submission Validator](https://aka.ms/gdkdl) 获得。

<a id="open-data-connections" />

### 由打开的数据连接导致的打包失败

当你使用 `xbapp install /w` 安装包时,或者当 **XBOX Manager** 在启用了 **Keep data connection open**(保持数据连接打开)选项的情况下安装包时(用于智能交付和按需区块场景),在安装完成后,主机与 PC 上的包文件之间的数据管道会保持打开。此打开的连接会锁定包文件。

如果你在此管道打开时尝试重新构建或重新打包游戏,`makepkg` 会因共享冲突而失败,因为它无法写入被锁定的包文件。

**要解决此问题,请在重新构建之前关闭打开的数据连接:**

* **XBOX Manager**:在 XBOX Manager 应用中,找到已安装的包并取消勾选 **Keep data connection open** 选项,或者在不启用该选项的情况下卸载并重新安装包。
* **xbapp install**:在不需要管道在安装后保持打开时,省略 `/w` 标志。仅当你的游戏需要在开发测试期间在运行时请求额外区块时才使用 `/w`。
* **关闭 XBOX Manager**:完全关闭 XBOX Manager 会释放它对包文件持有的任何打开文件句柄。

<Tip>如果你使用的引擎集成(例如 Unreal Engine 的 XBOX 平台工具)将包文件输出到固定的输出目录,请确保 XBOX Manager 在触发新的构建之前释放该文件。在构建之间改变输出目录也是避免冲突的另一种方式。</Tip>

<a id="resources_and_guidance" />

## 资源与指导

有关详细信息,请参见以下文章:

* System > Overviews > [流式安装与智能交付概述](/build/core-features/common/packaging/overviews/streaming_install-intelligent_delivery)
* System > Overviews > Streaming Installation > [动态重排区块](/build/core-features/common/packaging/packaging-chunkreordering)
* System > Overviews > Streaming Installation > [流式安装:状态](/build/core-features/common/packaging/packaging-installstatus)
* Test, Automation, and Publishing > Tools > Streaming Installation > [部署包架构](/build/core-features/common/packaging/deployment/atoc-deployment-schema)
* Test, Automation, and Publishing > Tools > Streaming Installation > [Make Package (makepkg.exe)](/build/core-features/common/packaging/deployment/makepkg)

<a id="see_also" />

## 另请参见

[MicrosoftGame.config](/build/core-features/common/game-config/MicrosoftGameConfig-toc)
[Submission Validator (SubmissionValidator.dll)](/build/core-features/common/packaging/subval/submissionvalidator)
[Submission Validator 质量测试](/build/core-features/common/packaging/subval/submissionvalidator-tests)
[XBOX Manager:管理应用和文件](/tools/tools-console/xbom/manager-tool-managing-applications#deploying-apps)


## Related topics

- [开发过程中的应用打包](/zh-CN/build/core-features/common/packaging/packaging-packaging-during-development.md)
- [Submission Validator (SubmissionValidator.dll)](/zh-CN/build/core-features/common/packaging/subval/submissionvalidator.md)
- [Submission Validator 质量检查](/zh-CN/build/core-features/common/packaging/subval/submissionvalidator-tests.md)
- [Submission Validator 消息](/zh-CN/build/core-features/common/packaging/subval/submissionvalidator-messages.md)
- [流式安装与智能交付概述](/zh-CN/build/core-features/common/packaging/overviews/streaming_install-intelligent_delivery.md)