SaveFetch

SaveFetch

一款《星露谷物语》的SMAPI模组，在游戏每次保存时，将你的存档摘要上传到伴侣网站。通过浏览器登录一次——之后它就在后台静默运行。

SaveFetch预览查看大图

描述

我开发 SaveFetch 是为了将我的星露谷物语存档同步到我为自己和女朋友搭建的一个小网站上，用来追踪我们的农场——不公开，只是我们两个人的小项目。我分享这个模组本身，是希望万一有人也想搭建自己的伴生网站，而需要游戏端的这一半管道。

SaveFetch 不附带捆绑网站——你可以通过 config.json 让它指向你自己的服务器。设置好登录/上传 URL 后，你只需在浏览器中登录一次（模组不会直接处理你的密码——你的服务器会返回一个短期有效的 JWT 访问令牌，模组将其存储在本地，并用于以后自动认证上传，过期时会自动刷新）。从此以后，每次你保存游戏时，模组就会将你农场的快照发送到你的服务器——无需手动导出，也无需记住任何操作。

一切都在后台静默运行——不改变游戏玩法，没有界面，只需一次性登录，之后自动同步。

每次保存时会发送以下内容：

  • 基本标识符——存档 ID、农场名称、农民名称、游戏/模组版本
  • 进度——游戏中的日/季节/年、游玩天数、总游戏时间
  • 金钱——当前余额和总收入
  • 技能等级——耕种、采矿、采集、钓鱼、战斗
  • 统计数据——制作的物品/烹饪的菜肴、钓到的鱼、杀死的怪物

此模组要求你拥有自己的网络服务器，并实现预期的 API 端点（登录重定向、存档上传、头像上传、令牌刷新）。它不是面向普通用户的即插即用工具——它是自托管设置中的客户端部分。如果你想为他人编写文档，可以参考 API 契约或 GitHub 仓库 这里。

SaveFetch — API 契约

要使用此模组，你的服务器需要实现四个端点。路径可以是任意的——模组会从 config.json 中读取完整的 URL（LoginUrl、SaveUrl、RefreshUrl、AvatarUrl）。

  1. 登录重定向 — GET {LoginUrl}?port={port}&state={state} 网络路由，会话认证。

    • 如果用户在你的网站上未登录，请先显示正常的登录页面。
    • 认证成功后，签发一个 JWT 访问令牌。
    • 将浏览器重定向到： http://127.0.0.1:{port}/callback?token={token}&username={name}&state={state}
    • state 必须原样返回——否则模组会拒绝回调（CSRF 防护）。

  2. 令牌刷新 — POST {RefreshUrl}（Bearer：过期访问令牌） 接收过期令牌，将其列入黑名单，并返回一个新令牌： { "access_token": "…", "token_type": "bearer", "expires_in": 28800 }

  3. 存档上传 — POST {SaveUrl}（Bearer 令牌，JSON 主体）

    {
  "saveId": 195023486,
  "farmerName": "Kim",
  "farmName": "Riverside",
  "uniqueMultiplayerID": 3141592653589793,
  "isHost": true,
  "gameVersion": "1.6.15",
  "modVersion": "1.0.0",
  "sentAtUtc": "2026-07-14T09:30:00Z",
  "day": 14,
  "season": "summer",
  "year": 2,
  "daysPlayed": 42,
  "playtimeMs": 10800000,
  "money": 125000,
  "totalMoneyEarned": 480000,
  "skills": { "farming": 8, "mining": 6, "foraging": 5, "fishing": 7, "combat": 4 },
  "stats": { "itemsCrafted": 120, "itemsCooked": 35, "fishCaught": 210, "monstersKilled": 310 }
}
    • 201 已存储 · 401 无效/过期令牌（模组会刷新并重试一次）· 422 负载格式错误。
    • 将记录归属于经过认证的用户（JWT 主题），绝不属于请求体中的任何内容。
    • 以 (user_id, save_id) 为键进行存储（如果希望按日查看历史记录，可加上游戏内日期）。
    • ⚠️ 在多人游戏中，money/totalMoneyEarned 是共享钱包数值——每个客户端报告相同数字，因此不要跨记录求和。

  4. 头像上传 — POST {AvatarUrl}（Bearer 令牌，multipart/form-data）

    • 单个文件字段，名称为 avatar——玩家的站立精灵图（约 128×192px 的 PNG）。
    • 仅当服装自上次成功上传后确实发生变化时才发送，因此请将其视为“替换当前头像”，而非“添加新头像”。
    • 201 已存储 · 401 无效/过期令牌（与存档上传相同的刷新/重试）· 422 缺少/无效文件。

安装说明

  1. 如果尚未安装 SMAPI，请先安装。
  2. 下载此模组并将其解压到你的 Stardew Valley/Mods 文件夹中。
  3. 在 config.json 中配置你的网站/应用程序 API 端点。
  4. 通过 SMAPI 启动游戏。
  5. 在 SMAPI 控制台窗口中，输入 savefetch_login 并按回车——这将打开你的浏览器，以便登录你的网站/应用程序。
  6. 登录后，关闭浏览器标签页并返回游戏。大功告成——此后存档将自动上传。

主要功能

  • 一次性浏览器登录 — 无需在游戏或控制台中输入密码；认证在你的浏览器中安全进行。
  • 自动存档同步 — 每次游戏保存时，农场摘要（金钱、技能等级、统计数据、游戏时间、日/季节/年）都会上传到你在网站/应用程序上的个人资料中。
  • 自动头像同步 — 角色当前服装会在变化时被渲染并上传，因此你的个人资料图片始终与你的农民形象匹配。
  • 多人游戏感知 — 对农场工人同样适用；每个玩家的统计数据都归属于他们自己的账户。
  • 控制台命令 — savefetch_login、savefetch_status（检查登录状态和上次上传结果）以及 savefetch_logout。
  • 无性能影响 — 上传在后台线程中进行，绝不会暂停或冻结游戏。

要求

  • SMAPI 4.0.0 或更高版本
  • 星露谷物语 1.6.0 或更高版本
  • 你自己的网络服务器/API，实现登录、存档上传、头像上传和令牌刷新端点——没有它，此模组无法开箱即用

致谢

感谢 SMAPI 团队，这个模组构建在他们开发的模组框架之上。

源代码 这里