nxapi SplatNet 3数据下载教程:对战结果、Splatfest记录与自动监控完全指南
nxapi SplatNet 3数据下载教程:对战结果、Splatfest记录与自动监控完全指南
nxapi 是一个开源的 Nintendo Switch Online 应用 API 工具,它的 SplatNet 3 数据下载功能可以把你《Splatoon 3》的对战结果、Splatfest 记录、照片相册等数据一键导出为 JSON 文件,还支持 7×24 小时自动监控新数据。本教程将带你从安装登录一直配置到无人值守的后台监控。
1. 认识 nxapi:任天堂 Switch 数据工具包
nxapi 提供命令行(CLI)、Electron 桌面应用和 TypeScript 库三种形态,核心能力包括:
- 📥 下载 SplatNet 3(Splatoon 3)、SplatNet 2(Splatoon 2)的全部个人游戏数据
- 🎮 在 Discord 展示 Nintendo Switch 在线状态,附带 Splatoon 3 额外信息
- 📢 好友在线桌面通知、NookLink 报纸下载、Parental Controls 使用记录导出
命令行模式是最常用的数据下载方式,本教程围绕它展开,完整命令参考见 docs/cli.md。
2. 安装 nxapi 并登录 Nintendo Account
首先需要安装 Node.js,然后一条命令全局安装:
npm install --global nxapi
接着用交互式命令登录 Nintendo Account(会生成一个登录链接,在浏览器打开登录并把链接粘贴回终端,即可自动获取会话令牌):
nxapi nso auth
登录成功后,运行下面的命令验证 SplatNet 3 连通性,它会显示你在 Splatoon 3 中的玩家名、#ID、称号和首次游玩时间:
nxapi splatnet3 user
💡 所有 SplatNet 3 命令在令牌过期时都会自动刷新 Web 服务令牌(此过程会经过第三方 imink/flapg 认证 API)。如不希望自动刷新,可加
--no-auto-update-session。认证与令牌续期逻辑位于 src/common/auth/splatnet3.ts。
3. 下载对战结果:dump-results 命令详解
这是最常用的命令——把全部对战(普通/排名/私人/Splatfest 对抗)和**肥肥_salmon run(Coop)**战绩逐条落盘为 JSON 文件:
# 下载对战 + 协力结果到 data/splatnet3 目录
nxapi splatnet3 dump-results data/splatnet3
# 只下载对战结果 / 只下载协力(Salmon Run)结果
nxapi splatnet3 dump-results --battles
nxapi splatnet3 dump-results --coop
# 额外下载玩家历史与目录(目录武器/角色)记录
nxapi splatnet3 dump-results --include-history --include-catalog
下载产物说明:
| 文件 | 内容 |
|---|---|
splatnet3-result-<对局ID>.json |
单场对战详情(模式、地图、战绩、击杀数等) |
splatnet3-coop-result-<对局ID>.json |
单场 Salmon Run 详情(等级、金币、赏金鱼等) |
splatnet3-results-summary-<时间戳>.json |
对战历史分组摘要 |
splatnet3-coop-summary-<时间戳>.json |
协力战历史分组摘要 |
✅ 核心特性:已存在的对局文件不会重复下载,因此可以放心反复执行,天然适合作为增量备份脚本。实现见 src/cli/splatnet3/dump-results.ts。
4. 下载 Splatfest 记录:dump-fests 命令
Splatfest(祭典)是 Splatoon 3 的周期性大型对抗活动。一条命令即可导出你所在区域的全部祭典记录,包括各阵营名称、开始时间和状态:
# 下载全部 Splatfest 记录
nxapi splatnet3 dump-fests data/splatnet3
# 附带阵营排名数据
nxapi splatnet3 dump-fests data/splatnet3 --include-rankings
如果你只想知道当前区域有哪些祭典,不用下载文件,直接看终端表格即可:
nxapi splatnet3 festivals
相关源码见 src/cli/splatnet3/dump-fests.ts。
5. 其他 SplatNet 3 数据一键导出
| 命令 | 作用 |
|---|---|
nxapi splatnet3 dump-records |
下载全部玩家记录:历史、英雄(Boss 战)、目录记录、地图/武器统计 |
nxapi splatnet3 dump-album |
下载照片相册(Album)中的全部照片文件 |
nxapi splatnet3 battles |
终端表格列出最近 50 场对战,支持 --json |
nxapi splatnet3 friends |
列出玩过 Splatoon 3 的任天堂好友及活动信息 |
nxapi splatnet3 token --json |
输出 SplatNet 3 访问令牌,供你自己的脚本调用 API |
按需只取其中一类数据时,可用对应参数过滤,例如只下载武器统计:
nxapi splatnet3 dump-records --weapon
全部命令源码集中在 src/cli/splatnet3/ 目录。
6. 自动监控新数据:monitor 命令配置
monitor 命令会常驻运行,周期性轮询 SplatNet 3,发现新对局就自动增量下载——非常适合配合游戏习惯做到"玩完就有数据":
# 启动监控,新数据写入 data/splatnet3(默认 15 分钟检查一次)
nxapi splatnet3 monitor data/splatnet3
# 只监控对战结果,并把检查间隔设为 60 秒
nxapi splatnet3 monitor --battles --update-interval 60
# 同时监控协力战与照片相册
nxapi splatnet3 monitor --coop --album
# 有新对局时同步刷新历史/目录/地图/武器统计
nxapi splatnet3 monitor --include-history --include-catalog --include-stage --include-weapon
工作机制(实现见 src/cli/splatnet3/monitor.ts):
- 启动时全量下载一遍对战、协力和相册数据(可用
--battles/--coop/--album选择); - 之后每隔
--update-interval(默认 900 秒)只检查增量,有新对局才拉取,请求量极低; - 按
Ctrl+C停止时,会等当前更新完成再优雅退出。
⚠️ 建议将间隔保持在 60 秒以上,避免过于频繁地请求任天堂服务器。
7. 常见问题 FAQ
❓ 数据存放在哪里?
不指定目录时默认写入 splatnet3 子目录,位置为各平台的 nxapi-nodejs 数据目录(如 Linux 的 ~/.local/share/nxapi-nodejs)。可用 nxapi --data-path ./data 全局指定。
❓ 需要 Nintendo Switch Online 会员吗? 访问 SplatNet 3 这类游戏专属服务需要有效的在线会员资格(免费试用也可以)。仅使用 Parental Controls 数据则不需要。
❓ 不想用命令行,有图形界面吗? nxapi 自带 Electron 桌面应用(菜单栏形态),与 CLI 共享登录账号,可展示 Discord 状态、好友通知并打开游戏专属服务:
❓ 数据安全吗?会封号吗? nxapi 只读取你自己的数据,且请求频率远低于同类项目。历史上曾有个别用户被限制访问 SplatNet 3 的公开案例(2023 年 9 月,与 nxapi 无关的第三方应用),因此建议保持合理的轮询间隔,详见 README.md。
8. 延伸阅读
- 完整 CLI 命令参考:docs/cli.md
- SplatNet 3 GraphQL API 客户端源码:src/api/splatnet3.ts
- 作为 TypeScript 库使用 SplatNet3Api:docs/lib/splatnet3.md
- 认证流程源码:src/common/auth/splatnet3.ts
完成本教程后,你就拥有了一套完整的 Splatoon 3 数据备份方案:dump-results 负责对战存档、dump-fests 负责 Splatfest 档案、monitor 负责无人值守增量更新——所有 JSON 数据都可以随时导入自己的统计脚本或数据库。🦑


