把本地音乐变成能跨设备播放的曲库（Songloft）

把音乐放在本地是件省心的事，麻烦出在播放环节。手机、台式机、客厅电视各有一套播放器，曲库要复制好几份，改一次标签就得重新同步一轮。常见的解法是留一台常开的机器专门放音乐，其余设备只负责取流。

Songloft 是一个用 Go 写的自托管音乐服务器，扫描本地音乐目录生成曲库，通过内置 Web 界面和 Flutter 客户端在电脑、手机、电视上播放。

服务端的输入是一个或多个本地音乐目录。扫描会读取 MP3、FLAC、WAV、APE、OGG、Opus、M4A、M4B、WMA、AIF、AIFF、MKA 等音频格式的封面与元数据，也会把 MP4、MOV、MKV、WebM、AVI 这类视频容器认出来，探测到真实视频轨后在客户端里渲染画面。输出侧对应几种访问方式：浏览器打开服务地址用完整版自带的 Web 前端，Flutter 客户端覆盖 Android、iOS、macOS、Windows、Linux、Web 六端，Kodi 插件把播放界面搬到大屏设备上交给遥控器。项目仓库在 songloft-org/songloft，Apache License 2.0 授权，主要语言是 Go，当前 1862 star、151 fork、25 个开放 Issue，项目主页是 https://songloft.hanxi.cc/ 。

现有能力拆开看，规模比一个单纯的播放器大：

• 本地音乐管理：扫描本地目录，提取封面与元数据，覆盖 MP3、FLAC、WAV、APE、OGG、Opus、M4A、M4B、WMA、AIF、AIFF、MKA 格式。
• 视频支持：识别 MP4、MOV、M4V、MKV、WebM、AVI、TS、MPG、MPEG、FLV、WMV、RM、RMVB、3GP 等视频容器，在客户端内渲染画面。
• JS 插件体系：插件跑在 QuickJS 沙箱里，带权限模型、健康检查与热更新，用来扩展音源、元数据、设备控制这类能力。
• 跨平台客户端：Flutter 客户端支持 Android、iOS、macOS、Windows、Linux、Web 六端；Kodi 插件面向 Xbox、Apple TV、树莓派、Android TV，为遥控器操作做了适配。
• Bundle 本地模式：客户端内嵌 Go 后端，不用部署服务器，首次启动点击「使用本地模式」选择音乐目录即可播放本地文件。
• 网络歌曲与电台：可以添加网络音频 URL 与电台流，播放时透明缓存到服务端。
• 认证与接口：JWT 双 Token 机制（Access Token + Refresh Token）支持多设备管理，另有一份带 Swagger 文档的完整 REST API。
• 轻量运行：Go 编写、CGO-free、无外部依赖，官方给自己的定位是适合 NAS 与树莓派这类低功耗设备。

下面按实际用起来会撞上什么来组织：先列装完之后最先遇到的几件事，再逐条拆开，分清哪些是改不了的设计限制、哪些是调配置能绕开的，最后给出可行的替代做法与同类项目的横向位置。

装上之后最先遇到的事

仓库里提供了两条上手路径。二进制版本从 releases 直接下载对应平台的文件，完整版包名形如 songloft-linux-amd64、songloft-darwin-arm64、songloft-windows-amd64.exe；Docker 版本以 tar 包发布，按平台分为 songloft-docker-linux-amd64.tar、songloft-docker-linux-arm64.tar、songloft-docker-linux-arm-v7.tar。README 的推荐是初次使用直接下完整版，开箱就有 Web 界面；想在手机或电脑上独立使用、不部署服务器，就下 bundled- 系列。

# 完整版二进制（Linux x86_64）
https://github.com/songloft-org/songloft/releases/latest/download/songloft-linux-amd64

# Docker 镜像（Linux x86_64）
https://github.com/songloft-org/songloft/releases/latest/download/songloft-docker-linux-amd64.tar

# Bundle 版（Windows）
https://github.com/songloft-org/songloft/releases/latest/download/songloft-bundled-windows-x64.zip

Bundle 版的最短路径是：装好后首次启动点击「使用本地模式」，选择音乐目录，客户端就会用内嵌的后端扫描并播放这批文件，全程不涉及服务端部署。运行结果在客户端里看；服务端部署的情况下，曲库和歌单在 Web 界面和客户端各自的对应页面里查看。仓库的公开说明里没有写服务端的默认监听地址与启动端口，这一步需要对照文档站确认。

装好之后容易先碰到的几件事：

• 三种版本要先选一个：完整版带 Web 前端，-lite 不带，bundled- 系列是客户端内嵌后端、不用单独部署服务器。
• Docker 部署扫描本地文件，界面显示扫描完成之后，可能还有几个 ffmpeg 进程长期占着 CPU。
• Windows 客户端点退出后要等七八秒才真正关掉，期间伴随一次报错提示。
• 主仓库不预置任何第三方音源插件，想接网络音源得自己去社区找成品。
• 从 v2.13.0 起 WebF 渲染引擎被移除，声明了 renderEngine: "webf" 的插件在新宿主上装不上。

逐个拆开看

扫描完成后 ffmpeg 还在吃 CPU

触发条件是在 Docker 下点击扫描本地文件，同时设置里已经关闭自动扫描。表现是扫描界面提示完成，CPU 占用却长期停在 99~100%，进程列表里能看到 3~4 个 ffmpeg。当时的临时动作是 SSH 上去手动杀掉这些进程。反馈这条的 Issue 已经标为已解决，实际遇到时先确认自己跑的版本号是否落在修复范围之内。

Windows 客户端退出要等七八秒

在 Songloft 2.10.0 的 Windows 客户端上点退出，程序不会立刻关闭，要等 7 到 8 秒才退出，同时弹出报警提示。这是 2.10.0 在 Windows 客户端上的表现，对应 Issue 标记为已解决。

小爱音箱有灯光没声音

用智能音箱插件给小爱音响推歌时，音响有灯光反应但不出声，与音量大小无关；同一时期在线状态也偏，音响处于休眠待机却显示离线。另一条反馈发生在 MIoT 插件 2026.8.10 上，点歌单里的歌没反应，只有播放控件上的播放键有效，播放界面全屏后控件还会异常。这两条都在 dev 版本上复现，Issue 状态均为已解决。

yt-dlp 插件搜得到却播不了

yt-dlp 插件 2026.7.9 配 Songloft 2.9.4：搜索模式下 YouTube 能搜到歌曲，B 站大多数时候报 plugin call failed，但同一个词在搜索测试栏能通过；URL 模式下 YouTube 和 B 站都能提取到歌曲，建出来的歌单却基本无法播放。Issue 状态为已解决。

升级后插件装不上

v2.13.0 有一条 BREAKING CHANGES，WebF 渲染引擎被彻底移除。声明 renderEngine: "webf" 的插件在新宿主上安装或更新会被拒绝，存量已安装的条目由客户端回落到系统 WebView。属于版本升级带来的行为变化，不是偶发故障。

哪些是限制、哪些是配置问题

属于设计限制的先说清楚。WebF 渲染引擎从 v2.13.0 起不再支持，依赖它的插件在新版本上装不上，这一点改不了。插件生态由第三方社区维护，主仓库不预置、也不分发任何第三方音源插件成品，能装到什么取决于社区做到了哪一步。完整版、lite 版、Bundle 版在打包阶段就定死，不能靠改配置在三种形态之间切换。官方构建会上报匿名运行统计，内容是版本号与崩溃栈，想要零遥测只能自编译。

属于配置或版本匹配的是另一类。扫描行为、插件权限这类开关走服务自身的配置，仓库根目录有 .env.example 可以当字段参考，完整说明在文档站。yt-dlp、MIoT、智能音箱这几条反馈里，插件版本和宿主版本是绑在一起走的，单独升一侧容易复现旧问题。v2.12.0 为插件新增了 net:insecure-tls 权限，允许 fetch 跳过 TLS 证书校验，这类权限开关也属于配置层的选择。

Songloft 本身只管理本地文件，项目不内置、不分发任何受版权保护的音乐资源，也不预置第三方音源插件成品。接网络音源、用第三方插件拉流时，内容的版权归属与合规责任在使用者这一侧。这套工具可用于自有或已获授权的音乐资源，把它搭成面向不特定多数人的公开服务，会带来法律与平台层面的风险。

绕开的办法

1. 碰上 ffmpeg 残留占用，先对照自己的版本号确认是否落在修复范围内，再决定要不要临时终止进程，不要把杀进程当成长期方案。
2. 客户端退出慢、退出报错这类问题在后续版本里标记为已解决，升级到修复后的版本比在旧版本上找绕过写法省事。
3. 小爱音箱与 MIoT 相关的功能，把插件版本和宿主版本一起更新，只升一侧容易复现旧问题。
4. 想用网络音源，得自己去社区找仍在维护的插件，并先弄清楚它来自哪一方、申请了哪些权限。
5. 依赖 WebF 的插件在 v2.13.0 之后无法使用，涉及音源能力时需要自行评估替代方案。

同类自托管音乐服务的横向位置

如果只需要在浏览器里听自己的曲库，不装客户端，也用不到插件扩展，Songloft 的六端客户端与插件权限模型就成了多余的复杂度，epoupon/lms 这类以 Web 界面为中心的服务端更贴合这种用法。反过来，需要手机、电视、音箱各自独立播放，或者想用插件接网络音源时，Songloft 的客户端覆盖面与插件体系才是它的用处所在。

适合已经在 NAS 或树莓派上跑服务、曲库以本地文件为主、想要一套 Web 管理加多端播放的人；也适合愿意折腾 JS 插件、把不同音源和音响接进来的人。不适合只想在浏览器里点开就听、不愿维护服务端的人，不适合计划把音乐服务开放给不特定多数人使用的人，也不适合重度依赖 WebF 渲染插件、又暂时不打算迁移插件的人。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.3 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。