5分钟快速上手nxapi:npm安装、Docker部署与源码构建完全教程

原创2026-11-13 21:28:261,889 阅读

5分钟快速上手nxapi:npm安装、Docker部署与源码构建完全教程

🎮 nxapi 是一款面向 Nintendo Switch Online 与 Nintendo Switch Parental Controls(家长控制)应用 API 的开源工具集,包含 JavaScript 库、命令行工具和 Electron 桌面应用。它可以把你的 Nintendo Switch 在线状态(游戏、对战信息)显示在 Discord 上、在桌面接收好友上线通知,还能下载并访问 SplatNet 2/3、NookLink 和 Parental Controls 数据。本文提供 npm 安装、Docker 部署、源码构建 三种方式的完整教程,5 分钟即可跑通。

nxapi 桌面应用截图,展示 Discord 在线状态与好友列表

一、开始之前:了解 nxapi 能做什么

在动手安装前,先看看 nxapi 的核心能力(摘自 README.md):

功能 说明
Discord 在线状态 用 Switch 状态展示"正在玩"的游戏,支持显示好友代码,Splatoon 3 还有额外信息
好友上线通知 桌面原生通知,可针对多个好友
游戏服务访问 SplatNet 2/3、NookLink、Smash World 等(浏览器打不开的 NookLink 也能打开)
数据下载 批量导出 SplatNet 2/3 战绩、报纸、Parental Controls 使用记录
API 代理服务器 单个账号为多个用户获取状态,自动处理认证并缓存数据

💡 需要 NSO 会员吗? 不需要。唯一要求是你的 Nintendo Account 曾关联过一台 Switch 主机(Network Service Account)。只有使用游戏专属服务(如 NookLink)时才需要有效的在线会员。

Discord 中展示 Splatoon 3 在线状态的活动卡片

二、方式一:npm 一键安装(最快)

✅ 适用场景:本机已安装 Node.js 和 npm 的用户。

这是最省事的安装方式,一条命令全局安装 nxapi 命令:

npm install --global nxapi

安装完成后,运行 nxapi --help 即可看到全部子命令。CLI 命令的详细用法可以参考官方文档 docs/cli.md。

三、方式二:Docker 部署

✅ 适用场景:想部署 API 代理服务器 / Presence 服务器,或不想在本机装 Node.js 环境的用户。

项目内置了多阶段构建的 Dockerfile:基于 node:20 编译 TypeScript 后打包成精简的 production 镜像,数据统一存放在容器内 /data 目录(即 NXAPI_DATA_PATH),并创建了名为 data 的持久化卷。

1️⃣ 构建镜像

docker build . --tag nxapi

2️⃣ 挂载数据目录运行

docker run -it --rm -v ./data:/data nxapi nso user

📌 -v ./data:/data 把宿主机 ./data 目录挂载为数据目录,账号令牌等数据会保存在这里,容器删除后依然保留。

3️⃣ 用 docker compose 部署代理/状态服务器

仓库提供了现成的 docker-compose.yml,内置两类服务:

  • znc-proxy:Coral/znc API 代理,让一个账号为多个用户获取数据;
  • presence-server(需 --profile presence-server 启用):Presence 服务器,可为浏览器、脚本等外部程序提供状态查询接口。
# 启动 znc 代理
docker compose up -d znc-proxy

# 启动 presence server
docker compose --profile presence-server up -d

四、方式三:源码构建

✅ 适用场景:开发者,或想在 Electron 桌面应用 与 CLI 之间切换使用的用户。

克隆仓库

git clone https://gitcode.com/gh_mirrors/nx/nxapi
cd nxapi

⚠️ 建议用 git 克隆而非下载压缩包——nxapi 会检测当前 git revision 用于版本判断。

安装依赖并编译

npm install    # 安装依赖(Electron、TypeScript 等见 package.json)
npx tsc       # 编译 TypeScript

安装 CLI 或构建桌面应用

# 全局安装 nxapi 命令(也可直接用 node bin/nxapi.js ...)
npm link

# 构建 Electron 应用(使用 rollup 打包)
npx rollup --config
# 启动应用
nxapi app

🔧 源码构建注意:默认使用 nxapi-znca-api 完成 Coral 客户端认证。2025 年 6 月起该服务要求通过 nxapi-auth 认证,源码构建时需要在 nxapi-auth 客户端注册页 注册一个 OAuth 客户端(scope 为 ca:gf ca:er ca:dr),并把 Client ID 写入 nxapi 使用的 .env 文件(变量 NXAPI_AUTH_CLIENT_ID)。从 npm 或 Docker 镜像安装则无需此步骤。

构建 Docker 镜像(源码方式)

docker build . --tag nxapi

五、首次使用:登录 Nintendo Account

无论哪种安装方式,首次使用都建议先登录(详见 src/cli/nso/auth.ts 对应命令):

# 交互式登录:生成登录链接,自动获取 session token
nxapi nso auth

# 查看已认证的账号信息
nxapi nso user

登录成功后,就可以尝试几个高频命令:

nxapi nso friends          # 查看好友列表
nxapi nso presence         # 查看自己的在线状态
nxapi nso notify           # 开启好友上线桌面通知

macOS 菜单栏中的 nxapi 应用,展示账号切换、Web services 与 NookLink

六、常见问题(FAQ)

Q1:数据存在哪里? 默认保存在各操作系统的用户数据目录(Linux 为 ~/.local/share/nxapi-nodejs)。可用 nxapi --data-path ./data 或环境变量 NXAPI_DATA_PATH 指定位置。

Q2:如何开启调试日志? nxapi 使用 debug 包:

DEBUG=nxapi:*,cli,cli:* nxapi ...      # 查看全部调试日志
DEBUG=nxapi:api:* nxapi ...            # 查看全部 API 请求

Q3:我的账号会被封吗? 官方 README 的说明是"极不可能":splatnet2statink 等同类项目使用同样的反编译 API 已运行多年无人被封;且 nxapi 的 Discord 状态功能使用小号获取数据,主账号并不直接参与请求,风险极低。

Q4:Electron 应用在 Linux 上连不上 Discord? 这是沙箱(snap/flatpak)问题:dpkg 和 AppImage 版 nxapi 未被沙箱化可正常使用,snap 版 nxapi 或 snap 版 Discord 则无法支持 Discord Rich Presence。

七、下一步去哪里?

至此,npm 安装、Docker 部署、源码构建三条路线已全部覆盖——现在打开终端,输入 nxapi,让你的 Switch 状态出现在 Discord 上吧!✨

登录后查看全文
nxapi