NeriPlayer 完全指南：从安装到多设备同步的实战教程

项目	内容
软件	NeriPlayer
版本	95a21a6.01041213
平台	Android APK
体积	10.47M
分类	影音播放
包名	moe.ouom.neriplayer
官网	NeriPlayer 官网
下载一	NeriPlayer 下载，NeriPlayer 下载
下载二	NeriPlayer 下载，NeriPlayer 下载
文档	NeriPlayer 文档
介绍	NeriPlayer 音理音理是一款轻量的本地音频播放器，支持自动扫描整理、锁屏控制，还能通过 GitHub 同步歌单和播放统计。本文带你从零开始配置，并解锁一起听、SponsorBlock 等高级功能。

NeriPlayer 是什么

NeriPlayer，中文名叫音理音理，是一款主打本地播放的 Android 音频播放器。它的定位很明确——把你手机里散落的 MP3、FLAC、WAV 等格式文件一扫而尽，自动按专辑、艺术家整理归档，再加上一些实用的在线联动功能，比如 GitHub 私有仓库同步歌单、和朋友一起听同一首歌。

如果你用腻了网易云、QQ 音乐这类重联网播放器，想回归纯本地播放但又不想牺牲同步能力，NeriPlayer 正好踩在这个缺口上。它的安装包只有 10M 出头，界面设计也走极简路线，没有广告、没有推荐信息流，打开就是你的音乐库。

这篇教程结束时，你会完成三件事：正确安装并初始化 NeriPlayer、把歌单和播放统计同步到你自己的 GitHub 私有仓库、知道怎么和朋友建一起听房间。

前置条件

在动手之前，确认以下几点：

• Android 手机：没有 iOS 或桌面版本，仅限 Android APK 安装
• 存储空间：安装包 10.47M，扫描和解析音乐库不占额外空间，但建议手机至少预留 50M 空白
• GitHub 账号：配置同步功能时需要一个 PAT（个人访问令牌），需要 repo 权限
• 本地音乐：如果只有在线流媒体而没有本地文件，NeriPlayer 的核心价值会打折扣

分步骤实操

第一步：安装与首次启动

安装方式和普通 APK 没有区别，但注意一点——NeriPlayer 目前没有上架任何主流应用商店，只能从第三方渠道获取。安装时如果系统弹出"未知来源"警告，在设置里放行即可。

首次打开应用会走一个完整的引导流程：Loading → Disclaimer → Onboarding → Main。启动过程中不要中途杀进程，否则会跳过初始化导致后续功能异常。进入主界面后，你会看到底部三个标签：Library（媒体库）、Explore（探索）、Settings（设置）。

第二步：扫描本地音乐

进入 Library 标签，应用会自动开始扫描手机存储中的音频文件。这个过程完全在本地完成，不上传任何数据。扫描完成后，你会看到按艺术家、专辑、歌曲三种视图排列的音乐库。

如果扫描结果不全，可以手动检查两个地方：

1. 设置 → 扫描路径：确认 NeriPlayer 有权访问你存放音乐的目录（有些国产 ROM 需要手动授权存储权限）
2. 文件格式：NeriPlayer 支持 MP3、FLAC、WAV 等主流格式，不支持 APE 或专有加密格式

第三步：配置 GitHub 同步

这是 NeriPlayer 最有特色的功能——歌单、收藏、播放统计全部同步到你自己的 GitHub 私有仓库，不经过项目维护者的任何服务器。

操作路径：Settings → GitHub 同步，按以下步骤填写：

1. 仓库所有者：你的 GitHub 用户名
2. 仓库名称：可以用已有仓库，也可以点应用内的"一键创建私有仓库"按钮自动建好
3. 个人访问令牌（PAT）：去 GitHub Settings → Developer settings → Personal access tokens 生成，权限勾选 repo 即可

填完后点"测试连接"，成功后勾选你想同步的内容——本地歌单、收藏歌单、最近播放、播放统计、删除记录。同步有三种触发方式：手动点"立即同步"、变更后延迟同步、WorkManager 定时后台同步。

多设备场景下，同一 GitHub 仓库可以在多台手机上配置。合并策略很贴心：播放统计全量累计，歌单按版本化操作合并（双方同时修改歌单结构时保留各自意图），甚至跨设备删除事件也会同步——A 设备删掉某歌单，B 设备同步后也会跟着删。

第四步：发起一起听房间

想和朋友同步听同一首歌？进入现在播放页面 → 一起听 → 创建房间。创建时有一个硬性规则：

房间当前曲目必须是在线音源，本地歌曲不能建房或替换房间当前曲目

这个设计是合理的——听众需要能从同一音源获取播放地址，本地文件别人拿不到。创建后你成为房主，自动成为房间唯一成员，开始播放后朋友就可以加入了。

加入方式有两种：

• 邀请链接：房主复制完整链接发给朋友，链接里已经包含房间密钥
• 深链加入：朋友点链接后 NeriPlayer 深链协议自动识别，直接入房

一个安全细节：邀请密钥不会暴露在公开房间状态里，只有房主和首次加入的听众能拿到。房主离线后房间的恢复依赖 Durable Objects 持久化，不会因为房主断网整个房间就崩了。

第五步：启动器快捷方式

长按桌面 NeriPlayer 图标，会弹出四个快捷方式：

快捷方式	功能
继续播放	打开上次播放的队列，直接续播
打开探索	跳到 Explore 搜索页
打开媒体库	跳到 Library 歌单页
随机喜欢	随机播放"我喜欢的音乐"歌单

这四个快捷键做了安全兜底——如果指向的资源不存在（比如没有可恢复的上次队列、"我喜欢的音乐"为空），不会静默失败，会弹出提示告诉你为什么没生效。

常见卡点

卡点一：扫描后音乐库还是空的

90% 的情况是权限没给全。去系统设置 → 应用管理 → NeriPlayer → 权限管理，把"存储"权限设为"允许所有文件"。部分国产 ROM（MIUI、ColorOS、OneUI）默认只允许访问媒体文件，需要手动切换到所有文件模式。

卡点二：GitHub 同步测试连接失败

大概率是 PAT 权限不够或仓库名写错了。检查两点：

1. PAT 是否勾选了 repo 权限（只有 read 不够，需要读写）
2. 仓库是否存在且为私有仓库（公开仓库也能用，但数据可能被别人看到）

卡点三：一起听房间朋友进不来

排查顺序：

1. 确认房间当前曲目是在线音源（本地歌曲建房听众进不来）
2. 检查网络连接（房主和听众都需要稳定网络）
3. 让听众直接点邀请链接，不要手动输入深链协议

进阶一句话

如果玩腻了基础功能，可以试试 Bilibili SponsorBlock——默认关闭，手动开启后会跳过社区标注的片头片尾、广告、填充片段，而且一起听期间会自动关闭避免播放状态漂移，隐私上也只上传 BV 号的 SHA-256 前缀，不暴露你的账号或播放历史。

本文为个人基于网络公开资料整理编写，非官方内容，仅供学习交流参考；软件版权归原作者所有，请支持正版；使用过程中遇到问题请查阅官方渠道，本文不承担任何责任。