文献库 资源 新闻与更新 客服
语言
Steamworks 文献库
Steam 云
Steamworks 文献库 > 功能 > Steam 云
简述
Steam 云会在 Steam 服务器上自动存储您游戏的文件，这样您的玩家就可以从任意的计算机登录 Steam 并访问自己保存的游戏。
集成水平
在 Steamworks 网站上配置所需的文件路径。 另外，也可以在游戏程序内对 Steamworks 进行所需的 API 调用，以便游戏将文件枚举、读取、删除或写入 Steam 云。

Steam 云概览

Steam 云为您的游戏提供了一个简单而透明的远程文件存储系统。 在自动云配置中指定的文件或使用云 API 写入磁盘（创建、修改、删除等）的文件将在游戏退出后自动复制到 Steam 服务器上。

如果用户换了一台电脑使用，在游戏启动之前，文件会自动下载到新电脑上。 然后，游戏可通过云 API 读取文件，或像往常一样直接从磁盘读取文件。 请避免针对特定电脑的配置，例如视频设置。

Steam 客户端确保了文件在用户可能访问的所有电脑上都能保持同步。

用户可以在 Steam 云设置下通过取消勾选“为支持的程序启用 Steam 云同步”来全面禁用云同步。

用户还可以在每个游戏的属性中禁用单个游戏的云同步。

Spacewar_Cloud_Properties.png

备注和最佳实践


在每次会话开始和结束后，Steam 会为用户同步您游戏的 Steam 云文件；记住这点很重要。 任何在会话中发生改变的相符文件都会立即在会话后上传至云存储。 如果您的游戏要将非常大的文件，或是很多小文件，写入 Steam 云，那么这可能会对用户的网络带宽造成可见的影响，也会延迟他们关闭 Steam 或是重新启动游戏的速度。

总体来说，较小的文件处理起来会更好。 如果某用户的保存状态可拆分为频繁变动及不频繁变动的不同类型，我们建议为这些类型分别使用不同的文件。 这样一来，没有改变的状态就不会在每次会话后都重新上传了。

文件大小限制


Steam 云对文件大小的绝对限制可能会随着时间而改变。 以下是一些当前的限制和临界值：

大小限制
100MB调用 ISteamRemoteStorage::FileWrite 或 ISteamRemoteStorage::FileWriteStreamWriteChunk 的大小上限
256MB可能会造成所选择的存储终结点对用户的位置而言并非最佳，对上传/下载性能带来消极影响

存档文件路径

在决定于何处写入您的存档文件时，请务必确保该路径对当前用户来说是独一无二的。 若需要，您可以通过 ISteamUser::GetSteamID 获取用户的专有 Steam ID。 通过 GetAccountID() 获取用户的 accountID 后，就可以在创建存档路径时使用独一无二的变量。

跨平台存档


如果您的游戏支持多个平台，或者是您计划在未来支持多个平台，您应当在为游戏设置 Steam 云时考虑一下跨平台存档。

如果您计划通过 ISteamRemoteStorage 接口直接读写文件，那么可以使用 ISteamRemoteStorage::SetSyncPlatforms 来控制平台之间的同步。 默认新文件会同步至所有平台。

如果您计划使用 Steam Auto-Cloud，需要知道以下几个关键点： 首先，默认情况下，新文件仅会同步至相关自动云根路径的操作系统设置。 也就是说，如果您为每个操作系统设置了不同的根，那么所有文件都将会被分隔在自己的平台上，也就不会有跨平台存档功能了。

若要启用跨平台存档，您应当转而定义一个单一的根路径（很可能需要为 Windows 这么做），然后为其他支持的平台创建先决根替代。 和给定根路径相符的文件若同时也有平台根先决替代，就会在原根路径和所有先决替代中同步至所有平台。 请参阅 Steam 自动云文档，以获取更多详细信息。

初始设置

要设置 Steam 云，您必须在 Steamworks 应用管理员面板中的 Steam 云设置页面设置每个用户的字节配额与每个用户的文件数量配额选项。

此配额按用户、按游戏在每款启用云的游戏上强制执行。 我们建议您为您的游戏设置合理的值。

注意： 务必点击页面底部的“保存”，并发布您更新的设置。 发布后，拥有您的游戏的所有人都将在 Steam 客户端看见云图标。

如果您的游戏已经公开发布，那么您可以勾选标有仅为开发人员启用云支持的复选框。 如果启用了仅限开发者模式，那么只有拥有您产品的“Developer Comp”权限的 Steam 帐户才能看见云图标和使用 Steam 云。 这样即可安全地测试 Steam 云集成，也不会破坏公共用户体验。 这对于未发行游戏不会造成任何影响，因为还没人拥有该游戏，他们无法看到或访问该特定 App ID 的任何云存储。

通过填写共享的云 App ID 字段，您可以在两个 App ID 之间共享云存储空间。 此操作最常用于在试用版和完整版之间共享游戏存档。 值为 0 则禁用此功能。

Steam 云 API 和 Steam 自动云

Steam 提供了使用 Steam 云的两种不同方法，请继续阅读以了解这两种方法的不同之处，确定哪种方法最适合您的应用程序。

首先是 Steam 云 API。
该云 API 提供了一系列的功能，允许您直接将 Steam 云集成到您的游戏中。 该云 API 将单个 Steam 用户文件互相分离，从而加大了对 Steam 云的控制程度。

Steam 云 API 通过 ISteamRemoteStorage API 接口公开，您可以在 Steamworks API 示例应用程序（SpaceWar）项目中找到示例用法。

其次是 Steam 自动云。
Steam 自动云专为您选择不集成 Steam 云 API 的游戏而设计。 它虽然上手快速简便，但缺乏 Steam 云 API 提供的灵活性。

如果您偏好更加深度地集成 Steam Cloud（比如，允许选择将哪些存档文件存储在云端），那么您应该使用云 API。 如若不然，您可以使用 Steam 自动云。

Steam 自动云

Steam 自动云是 Steam 云 API 的替代品，无需编写代码或以任何方式修改游戏，应用即可使用 Steam 云。 您只需指定出想要保存到云上的文件组。 Steam 将在应用程序启动和退出时自动同步文件组。 请避免针对特定电脑的配置，例如视频质量。
注意：将会在您的 Steamworks 云路径指明的每个位置生成 steam_autocloud.vdf 文件。 该文件由 Steam 使用，您的游戏可忽略。

设置

完成初始设置后，Steam 自动云的配置栏将在 Steam 云设置页面解锁。

根路径对保存至 Steam 云中的文件组进行了描述。 每个根路径可以具体到单个文件，也可以宽泛地表示某个子文件夹下的所有文件。 请使用一个新的路径来同步每组文件。

一个根路径由 5 个部分组成：

  1. 根

    这是一个预先确定的路径列表，游戏保存通常位于此处。
    根支持的操作系统对应路径
    应用安装目录全部[Steam Install]\SteamApps\common\[Game Folder]\
    SteamCloudDocuments全部平台特定路径，例如：在 Linux 上为 ~/.SteamCloud/[username]/[Game Folder]/
    WinMyDocumentsWindows%USERPROFILE%\My Documents\
    WinAppDataLocalWindows%USERPROFILE%\AppData\Local\
    WinAppDataLocalLowWindows%USERPROFILE%\AppData\LocalLow\
    WinAppDataRoamingWindows%USERPROFILE%\AppData\Roaming\
    WinSavedGamesWindows%USERPROFILE%\Saved Games\
    MacHomemacOS~/
    MacAppSupportmacOS~/Library/Application Support/
    MacDocumentsmacOS~/Documents/
    LinuxHomeLinux~/
    LinuxXdgDataHomeLinux$XDG\_DATA\_HOME/

    关于 Windows %USERPROFILE% 路径的说明：上文列出的相应路径是默认位置。 现在用户可以配置自己的 Windows 安装，将这些文件夹放到不同的位置（不一定在 %USERPROFILE% 下）。 无论这些文件夹的位置是默认的还是自定义的，Steam 都会使用必要的 Windows API 找到其当前位置。

  2. 子目录

    与根相关的云存储文件的子目录路径。 如子目录不存在，请使用“.”。

    自动云特殊路径值
    自动云允许在子目录路径中使用唯一的 Steam 用户标识符。 您可以为使用电脑的每位 Steam 用户单独存储文件。 您可以在您的游戏中使用 ISteamUser::GetSteamID 获取当前用户的 SteamID 或 AccountID，用于保存和读取。
    • {64BitSteamID} - 在 Steam 路径中使用此变量，插入用户的 64 位 Steam ID。 64 位的 Steam ID 示例：76561198027391269
    • {Steam3AccountID} - 在 Steam 路径中使用此变量，插入用户的 Steam3 帐户 ID。 帐户 ID 示例：67125541
    示例：SavesDir/{64BitSteamID}

  3. 模式

    匹配的文件掩码模式。 您可使用 * 作为通配符。 如果您希望目录中包括所有文件，只需使用 *。

    示例：*.sav

  4. 操作系统

    设置作为这些文件同步来源的和同步目的地的操作系统。 仅在文件为操作系统专用时才作要求，希望不会出现这种情况！

  5. 递归

    查找匹配文件时包括子目录下的文件。 此操作对于具有非确定性名称，例如非 Steam 用户名或 ID 的子目录很有帮助。 如果使用 Steam ID，强烈推荐在子目录字段中使用特殊路径值。

根先决替代

如果您的应用程序是跨平台的，并且每个操作系统都需要不同的目录，您可以使用根先决替代功能为上面设置的根路径指定一个先决替代。

上面指定的根路径能够被先决替代，以对应另一个操作系统上的不同路径。 如果您使用根先决替代，则必须在上述根路径的“操作系统”下拉菜单中指明[所有操作系统]。

根先决替代由 5 个部分组成。

  1. 原始根

    对应于您上面设置的根之一。

  2. 操作系统

    使用此先决替代的操作系统。

  3. 新根

    原始根映射到指定操作系统的新位置。

  4. 添加/替代路径

    您可以选择性地添加插入到新根和原始子目录之间的子目录路径。

  5. 替代路径

    一旦启用，将导致在“添加/替代路径”中指定的路径完全替换原始子目录。

示例：为 Unity 应用程序配置自动云

下面是一个为配合 Unity 和 Application.persistentDataPath 属性使用而设置自动云的例子，在此例中，每个操作系统的值都不同。 Windows 版本被配置为根路径， Unity 中的公司将设置为 DefaultCompany，项目名设置为 AutocloudSample。 在 macOS 和 Linux/SteamOS 上，在“添加/替代路径”字段中设置 Application.persistentDataPath 的替代路径，并启用“替代路径”。

有了这些设置，自动云文件将在三个文件夹中同步，如预览示例所示。

Cloud_Unity_Auto-Cloud_Example.png

预发行测试

如果您正在为已发行游戏添加 Steam 自动云，并且您已经在初始设置中启用了仅限开发者模式，那么您必须完成一些额外的步骤来测试功能。
  1. 登录一个拥有您要测试应用的 Steam 帐户。
  2. 在您的浏览器中导航至 steam://open/console，打开 Steam 控制台。
  3. 在控制台中输入 testappcloudpaths<AppId> 以及您正在测试的给定 App ID， 如：testappcloudpaths 480。
  4. 在控制台中输入 set_spew_level 4 4。
  5. 从 Steam 启动您的应用程序。
  6. 检查控制台活动，如果文件已经存在于自动云路径中，那么您应该看到文件被上传。 否则，从您的应用程序中保存一些文件，然后关闭此应用程序来触发同步。
  7. 换一台 PC，重复以上步骤，以测试从 Steam 自动云下载文件。
  8. 确保在所有支持的操作系统上进行测试。
  9. 设置 testappcloudpaths 0 与 set_spew_level 0 0 以结束测试。 您可重新启动 Steam 客户端以删除控制台选项卡。

不要忘记禁用仅限开发者模式，并在完成测试时发布更改。

动态云同步


Steam 云现支持动态同步——在应用程序会话期间，Steam 云上出现的更改可以下载至本地电脑。 当前的示例是 Steam Deck 上暂停的游戏会话。 只要应用标记为支持同态云同步，Steam 就会在暂停时将文件上传至 Steam 云。 然后用户就可以在另外的设备上运行游戏，在启动时就会受到来自 Steam Deck 会话的更新。 退出时，做出的更改也会被上传至 Steam 云。 最后，当唤醒 Steam Deck 设备时，Steam 就会将更改同步至该设备，并在应用程序上显示本地文件已更改的通知。 然后应用就可以循环访问这些更改，并采取相应操作。 比如，游戏可能可以从磁盘加载更新后的进度，让用户能够接着从其他设备上停止的地方玩下去。

请查看我们的公告，获取更多信息，包括创建此功能的原因，以及如何使用它。

请注意，不管应用程序是使用 ISteamRemoteStorage API 还是自动云来管理文件，都可使用此功能。

若要了解更多详情，请参见 ISteamRemoteStorage 文档，尤其是 ISteamRemoteStorage::RemoteStorageLocalFileChange_t、ISteamRemoteStorage::GetLocalFileChangeCount 和 ISteamRemoteStorage::GetLocalFileChange。

另外也请参见 ISteamRemoteStorage::BeginFileWriteBatch 和 ISteamRemoteStorage::EndFileWriteBatch——这两个包装器用于提示 Steam，以在用户发起系统挂起时，帮助 Steam 安全地同步到 Steam 云 。

预发行测试


您可以在本地为自己的应用启用动态云同步，以测试生成版本；我们推荐已推出的游戏使用此方法，因为如果为所有用户启用动态云同步，在运行不处理新 API 方法和回调的生成版本的情况下，会导致数据丢失。

若要在 PC 上进行本地测试，请按下方步骤进行：

  1. 登录拥有您要测试应用的 Steam 帐户。
  2. 在您的浏览器中导航至 steam://open/console，打开 Steam 控制台。 （您也可以使用命令行 steam -console 运行Steam，然后直接导航至控制台部分）。
  3. 在控制台中输入 @cloud_testdynamicsyncapp <AppId>，使用您正在测试的给定 App ID。 例：@cloud_testdynamicsyncapp 480
  4. 从 Steam 启动您的应用。
  5. 玩游戏至您理想的进度。
  6. 在 Steam 控制台中，输入 prepare_for_suspend。 Steam 将会挂起您的游戏进度，并将所有更改过的文件上传至 Steam 云。
  7. 可选：在另外一个设备上进一步玩游戏，然后退出，让 Steam 客户端将进度上传至 Steam 云。
  8. 回到原始设备，在 Steam 控制台中，输入 resume_suspended_games。 这将会从 Steam 云同步所有必需的文件，发送相关 API 至您的游戏，然后取消挂起游戏进度。

若要在 Steam Deck 上进行本地测试，请按下方步骤进行：

  1. 将您的 Steam Deck 连接至开发者套件。
  2. 若要使用 CEF 控制台，请参见此处。
  3. 在 JS 控制台中，输入 SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp <AppId>”) ，以启用测试。 您可以输入 SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp 0”) 来禁用测试。

调试

首先，请始终确保您已经在 Steam 合作伙伴网站上发布了您的更改，并已等待至多 10 分钟或已重新启动了您的 Steam 客户端来接收已发布的更改。

如果您的 Steam 云出现问题，您应该检查位于 %Steam Install%\logs\cloud_log.txt 的日志文件。

参见 Steamworks API 调试，了解更多信息。
Steamworks 是由 Valve 打造的一套工具和服务，帮助您在 Steam 上配置、管理和运营您的游戏。