5分钟快速上手nxapi:npm安装、Docker部署与源码构建完全教程
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 能做什么
在动手安装前,先看看 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)时才需要有效的在线会员。
二、方式一: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 # 开启好友上线桌面通知
六、常见问题(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。
七、下一步去哪里?
- 完整 CLI 命令文档:docs/cli.md
- 作为 TypeScript/JavaScript 库使用:docs/lib/index.md 与 src/exports/
- 各 API 的 TypeScript 类型定义:src/api/(含 Nintendo Switch Online、SplatNet 2/3、NookLink 等)
至此,npm 安装、Docker 部署、源码构建三条路线已全部覆盖——现在打开终端,输入 nxapi,让你的 Switch 状态出现在 Discord 上吧!✨


