维护提醒

BWIKI 全站将于 9 月 3 日（全天）进行维护，期间无法编辑任何页面或发布新的评论。

全站通知：

模组:制作指南/APIs/Update checks

来自星露谷物语维基
跳到导航 跳到搜索

← 模组:目录

每个 SMAPI 模组或内容包都可以受益于自动更新检查，因为这样做就能时玩家及时看到更新提示。这能帮助玩家确认他们的模组总是最新的，这可以提升游戏体验和减少支持请求。

介绍

启用更新检查

您可以向 [[../Manifest|manifest.json]] 添加更新键（update key）来检查更新。更新键会告诉 SMAPI 模组所在页面。例如，Nexus:2400 意为 Nexus ID 2400 的模组。 

"UpdateKeys": [ "Nexus:2400" ]

如果您提供了多个更新键，SMAPI 会检查所有键，并显示一个关于它找到的最新版本的提示（如果多个页面都是最新版本，会连接到列表上最靠前的页面）。 

"UpdateKeys": [ "Chucklefish:4250", "Nexus:541", "GitHub:Pathoschild/LookupAnything" ]

(SMAPI 也会从模组兼容性列表中抓取信息，因此在兼容性列表上的模组即使没有更新键也能检查更新。虽然如此，您仍应当在清单文件中添加更新键，以支持模组管理者和其他工具。)

可用网站

此处列出了受支持的模组网站：

模组网站 描述
Chucklefish （已过时） 确保您有一个模组发布页（一个包含 /resources/ 而非 /thread/ 的 URL）且具有 语义化版本，然后指定模组ID（模组页面 URL 的数字）。
"UpdateKeys": [ "Chucklefish:4250" ]
CurseForge 请确保最新版文件的显示名称包含一个语义化版本的后缀，且在版本和可选的文件扩展名前面有一个空格。例如，SMAPI 会识别如下的显示名称：1.3.0、Example Mod 1.10、Example Mod 1.10.0-prerelease.zip。
"UpdateKeys": [ "CurseForge:309243" ]
GitHub 确保您的 GitHub 项目有至少一个发布项，且最新发布的标签为一个语义化版本，然后指定您的 GitHub 用户名和项目名称。
"UpdateKeys": [ "GitHub:Pathoschild/LookupAnything" ]
SMAPI会通过发布标签（release tag）来获取版本。请注意 GitHub 的发布标签工作的方式，它无法支持“单仓库”，也就是多个模组放在同一个仓库中但其版本号不同。
ModDrop 请确保模组页面有一个语义化版本，然后指定模组ID（模组页面 URL 中的数字）。
"UpdateKeys": [ "ModDrop:123338" ]
SMAPI 会通过 "Main Versions" 下的文件获取最新版本。
Nexus Mods 确保 Nexus 模组有一个语义化版本，然后指定模组ID（模组页面URL中的数字）。当您在 Nexus 上创建新模组时，ID会出现在第一步后的 URL 中（在您需要上传文件之前）。
"UpdateKeys": [ "Nexus:541" ]
SMAPI 会从模组、"main files" 下载选项或 "optional files" 下载选项（永不优先）处获取版本。

高级

Beta版本

测试版（prerelease version，常称为alpha或beta版）在版本号中包含测试标签。例如，1.0.0-beta.5 是即将发布的 1.0.0 版本的测试版。

如果您同时提供测试版和非测试版，更新检查会依据玩家安装的模组版本检查更新：

  • 稳定版：安装稳定版的玩家将仅看到非测试版的更新提醒（除非主版本是测试版）
  • 测试版：安装测试版的玩家将看到最新版本的更新提醒，无论最新版本是测试版还是稳定版。

例如，假设您的模组有两个现行版本：1.7.0 和 2.0.0-beta。安装了 1.6.0 版本的玩家会看到 1.7.0 的更新提示，而安装了 1.6.1-beta 版本的玩家会看到 2.0.0-beta 的更新提示。

更新子键

SMAPI 假设每个模组页面仅有一个模组，因此会将版本最高者认定为最新版。这意味着在同一个页面发布多个模组会导致假性更新提示。例如，假设您在同一个 Nexus 页面提供了两个不同的模组：Geode Crusher (version 1.0.5) 和 Diamond Crusher (version 2.1.0)。若玩家安装了最新版的 Geode Crusher，他们会不停收到 2.1.0 版本的更新提醒，尽管那是另一个模组的版本。

您可以向升级键的末尾添加 @ 升级子键： 

"UpdateKeys": [ "Nexus:2400@GeodeCrusher" ]

当 SMAPI 从页面抓取多个可用的版本时，它仅考虑在标题或描述中包含 @GeodeCrusher（包括 @ 符号！）的文件。

警告：

  • 如果没有文件匹配子键，SMAPI 会忽略子键并进行正常的更新检查。
  • 对于 CurseForge 模组，SMAPI 不会检查文件描述中的更新子键，因为 CurseForge API 没有提供。
  • 对于 GitHub 模组，更新子键并没有什么用，因为仅会抓取最新发布。

在本地关闭更新检查

SMAPI 在后台检查更新，因此关闭更新检查并不会影响加载时间。

欲关闭更新检查：

  • 对于 SMAPI 和 全部模组：编辑 smapi-internal/config.json 文件，将 CheckForUpdates 设为 false。您将不再收到 SMAPI 或已安装模组的更新提醒，因此不推荐这样做。
  • 对于特定模组：编辑 smapi-internal/config.json 文件并将模组ID添加到 SuppressUpdateChecks 字段。

注意在您升级 SMAPI 后对 smapi-internal/config.json 所作编辑会丢失。参见该文件顶部的说明以创建永久性配置文件。

检查更新算法

下面是 SMAPI 决定向控制台输出哪一个更新提示的流程：

  1. 收集更新键：
    1. 从模组的清单文件中获取初始的更新键。
    2. 尝试在模组兼容性列表和 smapi-internal/metadata.json 中匹配模组ID，以添加不在清单文件中的更新键。
    3. 应用来自模组兼容性列表的手动更新键（update key override，用于模组清单或发布页给出的版本不正确的情形）。
  2. 获取可能的更新：
    1. 依照每个匹配的更新键收集应相应的版本（参见模组自动更新的可用网站）
    2. 根据以下原则过滤列表：
      • 模组的主版本；
      • 如果玩家安装了 beta 版 SMAPI 或安装了测试版模组或无法加载已安装的版本，则使用测试版（若可用）；
      • 模组兼容性列表收录的非官方版本；
      • 如果玩家使用 beta 版 SMAPI，可能使用非官方 beta 版。
  3. 根据过滤列表推荐最高版本。

如果多个模组页面都具有推荐的更新，则 SMAPI 提供指向第一个匹配项（按如下顺序）的链接：

  1. 模组清单文件的更新键中所列出的页面（按照列出的顺序）；
  2. SMAPI 的 smapi-internal/metadata.json 中的默认更新键；
  3. 模组兼容性列表中的更新键（顺序为 Nexus、ModDrop、CurseForge、ChuckleFish）；
  4. 模组兼容性列表中重写的更新键。

自定义更新清单

此部分高度专业化且支持特殊的边界情况（例如仅发布在 GitHub 仓库或自定义网站的模组）。大多数模组应当使用正常的更新键。

更新清单（update manifest）是一个放置在网站上的 JSON 文件，SMAPI 可以下载此文件以获取不在常见站点（例如 Nexus）上的模组的信息。例如，下面的清单文件列出了一个仅发布于自定义网站的模组的信息： 

{
    "Format": "4.0.0",
    "Mods": {
        "ExampleMod": {
            "Name": "Example Mod",
            "ModPageUrl": "https://example.org/mods/example-mod",
            "Versions": [
                { "Version": "1.0.0" }
            ]
        }
    }
}

下面是所需的字段（如无说明，不可省略）：

字段 使用方法
Format 清单文件格式的版本（当前为 4.0.0）。如果 SMAPI 之后改变了清单文件格式，则此字段可以使 SMAPI 正确解析旧版格式。
Mods 欲提供其信息的模组。可以列出任意数量的模组。

此字段为一个“字符串 → 数据模型”查询，其中

  • 键为更新子键（见上文）
  • 值为包含如下字段的数据模型：

每个模组都有如下字段：

字段 使用方法
Name 模组的显示名称，应当适于阅读。
ModPageUrl 玩家可以下载模组更新的网页的 URL。
Versions 可以下载的模组版本。可以列出任意数量的模组版本，其会根据通常的检查更新算法与玩家已安装的版本进行比对。

此字段为包含如下字段的数据模型所组成的列表：

自动 使用方法
Version 语义化版本号
ModPageUrl （可选）玩家可以下载此更新的页面的 URL，用于与模组自身的 ModPageUrl 不一致的情况。

欲使用自定义清单，模组须添加一个更新键，形如 UpdateManifest:<full URL to json file>@<mod key>。若上述的示例模组发布在 https://example.org/mod-updates.json，则其更新键会像下面这样： 

"UpdateKeys": [ "UpdateManifest:https://example.org/mod-updates.json@ExampleMod" ]

取自“https://wiki.biligame.com/stardewvalley/index.php?title=模组:制作指南/APIs/Update_checks&oldid=107673”