Feishin：现代化开源自托管音乐播放器 #

Feishin 是什么？ #

Feishin 是一款现代化的自托管音乐播放器，是知名播放器 Sonixd 的全新重写版本，由开发者 jeffvli 以 GPL-3.0 协议开源维护。它本身不存储音乐，而是作为客户端连接你自建的 Jellyfin、Navidrome 或 Subsonic 音乐服务器，把散落在服务器上的曲库变成一套美观、流畅、功能完整的播放体验。Feishin 同时提供 MPV 与 Web 两种播放后端，支持同步歌词、智能播放列表、播放记录回传等功能，并覆盖 Windows、macOS、Linux 桌面端以及网页端与 Docker 部署方式。对于厌倦了简陋 Web 播放界面、又希望完全掌控自有音乐数据的用户来说，Feishin 是一个兼顾颜值与功能的理想选择。

Feishin 有哪些亮点特色？ #

• 双播放后端自由切换：内置 MPV 播放器后端与 Web 播放器后端，桌面客户端可同时使用两者，兼容性更强、音质与格式支持更灵活，遇到特殊编码也能从容应对。
• 全面兼容主流自托管音乐服务器：原生支持 Jellyfin、Navidrome、Subsonic 三大协议，无需额外插件即可接入你已有的音乐库，Docker 部署时还可通过环境变量锁定服务器配置。
• 现代美观的界面设计：一改传统自托管客户端朴素老旧的观感，提供现代化的 UI 布局、封面墙、队列面板与播放详情页，并支持自定义主题扩展。
• 同步与未同步歌词支持：桌面客户端内置歌词自动获取能力，支持逐行同步歌词（LRC）与纯文本歌词展示，让听歌体验更完整。
• 播放记录回传服务器：可将播放行为 Scrobble 到你的音乐服务器，让收听统计、播放次数与推荐数据保持准确同步。
• Navidrome 智能播放列表编辑器：针对 Navidrome 用户提供图形化的智能播放列表编辑能力，无需手写规则即可按条件筛选曲目。
• 多平台 + 多形态覆盖：除 Windows、macOS、Linux 桌面客户端外，还提供托管网页版与官方 Docker 镜像（ghcr.io），服务器、NAS 播放场景同样适用。
• 完全开源、社区活跃：项目遵循 GPL-3.0 开源协议，GitHub 上已获得超过 1 万颗 Star、548 次 Fork，功能迭代与问题修复由社区持续推动。

免费下载 Feishin #

以下为官方提供的各平台安装包，点击链接即可下载。

提示：官方同时提供 Linux 版 AppImage 与 Flathub 版本，以及托管网页版 https://feishin.vercel.app 和 Docker 镜像 ghcr.io/jeffvli/feishin:latest，可按需选用。

Feishin 如何使用？ #

1. 启动客户端：安装完成后打开 Feishin，首次进入会看到服务器连接引导界面。官方推荐优先使用桌面客户端，因为它同时支持 MPV 与 Web 两种播放后端，并内置歌词抓取能力。
2. 添加你的音乐服务器：点击添加服务器，选择服务器类型（Jellyfin / Navidrome / Subsonic），填入服务器地址（http://地址:端口 或 https://地址:端口）以及用户名和密码。若使用 Docker 部署并启用了 SERVER_LOCK，则服务器名称、类型与地址会被预先锁定，用户只需填写账号密码。
3. 浏览与播放：连接成功后即可在左侧导航栏中按专辑、艺术家、歌曲、播放列表等维度浏览曲库。双击任意曲目即可开始播放，底部会出现播放控制条，支持进度拖动、音量调节、随机与循环模式。
4. 查看歌词与队列：在播放界面可展开歌词面板，同步歌词会随播放进度高亮滚动；队列面板可随时调整接下来要播放的曲目顺序。
5. 配置播放参数：进入设置可切换 MPV 或 Web 播放器后端、调整音质与转码策略、管理自定义主题，以及开关播放记录回传（Scrobble）功能。

Feishin 的常见问题？ #

MPV 播放时不断在暂停/播放之间快速切换怎么办？ 这是社区中反馈较多的问题，通常与 MPV 环境或音频输出设备有关。建议先在设置中切换到 Web 播放器后端确认问题是否消失，再检查系统中 MPV 的安装与音频驱动配置是否正常。

Feishin 支持哪些音乐服务器？ 官方明确支持 Jellyfin、Navidrome 和 Subsonic 三种类型（Docker 环境变量 SERVER_TYPE 中三者均可用，且值不区分大小写）。这三类服务器基本上覆盖了绝大多数自托管音乐方案。

Linux 上出现 “The SUID sandbox helper binary was found, but is not configured correctly” 报错怎么办？ 这是 Electron 应用在部分 Linux 发行版上的常见沙箱权限问题。官方提供的 AppImage 安装脚本会自动检测内核的 unprivileged_userns_clone 与 userns_restrict 设置，必要时为启动项追加 --no-sandbox 参数，使用官方脚本安装通常即可避免该问题。

如何添加自定义主题？ Feishin 支持主题自定义扩展，官方 README 中专门设有 “How can I add custom themes?” 条目，可参照仓库文档说明将主题文件放入对应目录后在设置中启用。

macOS 上打开提示“已损坏”或无法运行？ macOS 12（Monterey）及以上版本会对外部下载的应用启用隔离机制。官方文档提供了移除 quarantine 属性的操作说明，按步骤执行后即可正常启动；此外若需使用媒体键控制播放，还需在辅助功能中授权 Feishin 为受信任的辅助功能客户端，并重启应用使设置生效。

网页版和桌面版有什么区别？ 网页版（https://feishin.vercel.app）仅支持 Web 播放器后端，而桌面客户端同时支持 MPV 与 Web 两种后端，并额外内置歌词抓取能力。因此官方将桌面客户端列为推荐使用方式。

Feishin 如何安装？ #

Windows #

1. 根据你的设备架构下载对应的 .exe 安装包：Intel/AMD 处理器选择 win-x64.exe，ARM 设备（如骁龙笔记本）选择 win-arm64.exe，不确定时可直接下载通用版 win.exe。
2. 双击安装包，按向导提示完成安装。
3. 安装完成后从开始菜单启动 Feishin，即可进入服务器连接界面。

macOS #

1. Apple Silicon（M 系列芯片）Mac 下载 mac-arm64.dmg，Intel Mac 下载 mac-x64.dmg。
2. 打开 .dmg 文件，将 Feishin 图标拖拽到「应用程序」文件夹。
3. 若系统提示应用已损坏或来自未验证开发者，需按官方说明移除应用的 quarantine 隔离属性后再启动。
4. 如需使用键盘媒体键控制播放，请在系统设置中授予 Feishin 辅助功能权限，并重启应用使隐私设置生效。

Linux #

1. Flathub 安装：Feishin 已上架 Flathub，可直接通过 Flatpak 安装。
2. AppImage 脚本安装：运行官方提供的一键安装脚本，会自动下载最新的 .AppImage、赋予可执行权限、拉取桌面环境所需图标并生成 .desktop 启动项：

   dir=/your/application/directory
   curl 'https://raw.githubusercontent.com/jeffvli/feishin/refs/heads/development/install-feishin-appimage' | sh -s -- "$dir"
   

   如需启用原生 Wayland 模式，可在脚本后追加 wayland-native 参数（Electron 下为实验性特性，官方不提供正式支持）。
3. 安装后启动项应立即出现在应用菜单中；若未出现，注销并等待约 10 秒后重新登录即可。

Web 与 Docker #

1. 免安装方式：直接访问官方托管网页版 https://feishin.vercel.app（仅支持 Web 播放后端）。
2. Docker 方式：执行 docker run --name feishin -p 9180:9180 ghcr.io/jeffvli/feishin:latest 即可启动容器，默认映射 9180 端口。
3. Docker Compose 方式：在 docker-compose.yaml 中配置 SERVER_NAME、SERVER_TYPE、SERVER_URL、REMOTE_URL 等环境变量，可预设服务器信息并限制用户仅能修改账号密码。

Feishin 如何卸载？ #

Windows #

1. 打开「控制面板 → 程序和功能」或「设置 → 应用 → 已安装的应用」。
2. 找到 Feishin，点击「卸载」并按照提示完成移除。
3. 如需彻底清理，可手动删除 %APPDATA%\feishin 目录下的配置与缓存文件。

macOS #

1. 打开「访达 → 应用程序」，将 Feishin 图标拖入废纸篓。
2. 清空废纸篓完成卸载。
3. 如需清除残留配置，可检查 ~/Library/Application Support/feishin 与 ~/Library/Preferences 下的相关文件并手动删除。

Linux #

1. AppImage 安装方式：官方安装脚本自带卸载命令，运行以下命令即可同时删除 AppImage 文件、图标与 .desktop 启动项：

   dir=/your/application/directory
   curl 'https://raw.githubusercontent.com/jeffvli/feishin/refs/heads/development/install-feishin-appimage' | sh -s -- "$dir" remove
   

2. Flatpak 安装方式：执行 flatpak uninstall org.jeffvli.feishin 即可移除。
3. 卸载后如需清理残留，可手动删除用户配置目录下的 Feishin 相关文件夹。

Docker #

1. 停止并删除容器：docker stop feishin && docker rm feishin。
2. 若使用 Docker Compose，可在编排目录执行 docker compose down。
3. 如不再需要镜像，可执行 docker rmi ghcr.io/jeffvli/feishin:latest 清理本地镜像。