摘要Folia 是一款以全屏沉浸式歌词动画为核心体验的开源混合架构播放器支持本地音乐库、Navidrome 及网易云/酷狗等在线来源。它提供 Electron 桌面端与 Node.js Web 端两种形态具备增量扫描、白名单式内容过滤、多格式歌词解析与实验性模组系统。本文介绍其核心逻辑、功能边界、注意事项与完整使用流程。本地音乐播放器通常把“播放”做得很扎实却很少在歌词呈现上投入足够的设计资源而在线音乐客户端又往往受限于平台锁定无法自由接入本地文件或自建媒体服务器。Folia 选择了一条不太一样的路线以全屏沉浸式歌词动画为核心体验向上接入网易云、酷狗、Navidrome 等来源向下读取本地音频文件与同目录歌词同时提供 Electron 桌面端和 Node.js Web 端两种运行形态。如果你希望在一个播放器里统一管理本地无损音乐、自建媒体库和在线曲库并且愿意为歌词视觉效果留出足够的屏幕空间Folia 提供了一套开源、可自行部署的替代方案。工具背景与核心逻辑Folia 的定位是以歌词可视化驱动播放体验的混合架构播放器。它不是一个单纯的本地播放器也不是某个在线平台的第三方客户端而是把“音乐来源”和“歌词舞台”拆成两个相对独立的层面音乐来源可以是本地目录、Navidrome 服务器、网易云或酷狗歌词舞台则负责解析歌词时间轴并通过多种动画模式、AI 生成配色和响应式排版把全屏歌词渲染成近似文字 PV 的视觉效果。在技术实现上Folia 同时提供 Electron 桌面应用和基于 Node.js 的 Web 应用两种形态桌面版内置前后端运行环境适合即装即用Web 版可部署到 Vercel 或通过 Docker 自行托管。理解这一“混合架构”的边界很重要桌面版和 Web 版在功能覆盖和文件访问权限上并不完全等价本地音乐库的读取方式在两种形态下也存在差异。功能分点说明版本检测与更新Folia 桌面版和 Web 版均具备更新感知能力。设置中的版本信息会标注当前构建类型——官方桌面版、自部署Docker / Vercel / Cloudflare或非官方构建帮助用户判断更新路径。桌面版更新通常通过重新下载安装包覆盖完成Web 自部署用户则需要根据部署方式手动拉取新版本或重建容器。需要注意的是第三方 WebView 壳客户端Android APK的更新节奏与上游 Folia 并不一致不应将壳客户端的版本号等同于 Folia 本体版本。白名单式内容过滤以来源和格式为边界Folia 没有名为“白名单”的独立模块但它通过来源启用范围和本地文件格式白名单实现了等效的边界控制。在来源层面用户可以选择只启用本地音乐库、只接入 Navidrome或同时登录网易云 / 酷狗账号在本地扫描层面Folia 仅识别.mp3、.flac、.m4a、.wav、.ogg、.opus、.aac等音频扩展名歌词文件同样限定在.lrc、.vtt、.ttml、.qrc、.yrc、.krc范围内。.foliaignore文件还可通过 glob 规则将特定文件或目录排除在扫描之外。本地导入与增量扫描本地音乐库通过文件系统访问接口直接读取用户指定的文件夹索引信息保存在本地 IndexedDB 中音频文件内容不会被上传。扫描采用基于快照的增量策略系统记录每个文件的路径、大小和修改时间作为签名重扫时只处理发生变化的条目并支持复用未变动歌曲、识别已移除文件。同目录下的封面文件cover.png、cover.jpg、cover.jpeg和内嵌或同目录歌词会被自动关联本地歌曲还可以匹配在线歌词与封面也支持手动修正匹配结果。歌词舞台与模组系统实验性Folia 内置多种全屏歌词动画模式不同模式具有各自的排版氛围和可调参数并自动适配窗口尺寸。桌面版还提供实验性的Folium 模组系统可从模组市场安装经过认证的扩展用于添加歌词动画、背景、播放页图层或命令。模组生态属于加分项而非稳定承诺启用前应评估其与当前版本的兼容性。注意事项事项说明在线音乐功能受账号与地区限制网易云、酷狗等来源需要登录对应平台账号部分歌曲要求 VIP 权限或受地区版权限制Folia 本身不绕过这些限制。本地文件访问权限因平台而异Web 版依赖浏览器的 File System Access API桌面版的文件访问能力更完整移动端 WebView 壳客户端可能受 Android 存储权限模型影响首次使用需授予文件读取权限。macOS 未签名安装包可能被 Gatekeeper 拦截当前 macOS 包未做 notarize打开时提示“应用已损坏”通常不是文件损坏需要按照官方说明处理。Web 自部署不等于零维护Docker / Vercel 部署需要自行负责域名、端口、更新和 AI 密钥配置AI 配置留空不影响基础播放功能。在线曲库的可用性不由 Folia 保证第三方来源的接口稳定性、账号风控和地域策略均可能随时间变化播放失败时应优先排查来源侧状态。使用流程获取并安装 Folia访问 GitHub 上的 chthollyphile/folia-major 这个项目仓库根据操作系统和芯片架构下载对应安装包。Windows 运行.exe安装器macOS 将.dmg中的应用拖入 ApplicationsLinux 选择.deb、.rpm或 AUR 包完成安装。这里也为不想折腾 GitHub 的小白用户提供由热心网友整理好的安装包https://pan.quark.cn/s/dc1dcf149e8e首次启动与来源配置打开 Folia 后在首页顶部切换到所需的来源 Tab。如需使用本地音乐选择本地目录并授予读取权限如需接入在线曲库或 Navidrome在设置中完成对应账号登录或服务器地址填写。导入本地音乐库在本地来源中选择音乐文件夹。Folia 会自动扫描音频标签、封面和内嵌/同目录歌词并建立索引。库较大时首次扫描需要一定时间后续重扫走增量流程只处理新增或修改的文件。配置歌词与视觉按需进入视觉设置选择歌词动画样式如需透明背景、主题配色调整或 AI 主题生成在对应选项中开启。桌面版用户可进一步浏览 Folium 模组市场安装经过认证的扩展。检查更新与维护在设置中查看当前版本和构建类型。桌面版用户在 Release 有新版本时重新下载安装包覆盖更新自部署 Web 用户根据部署方式更新容器或项目。第三方壳客户端用户应关注壳项目自身的 Release 说明不要混用版本号。使用范围提醒Folia 的在线曲库接入依赖于第三方平台账号与接口其可用性、账号状态和内容版权均不由 Folia 项目方控制本地音乐库功能面向用户自行持有且有权访问的音频文件。在部署 Web 版或使用模组系统时应自行评估托管环境的安全配置和第三方扩展的来源可信度。本项目采用 AGPL-3.0 许可证分发修改版本时需遵守相应的开源义务。