二十分钟把 Folia 歌词动画播放器装进手机，免 App 也能离线看歌词
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia 没有官方手机 App，但 Web 版原生支持 PWA（可安装的网页应用，装进主屏幕后就以独立应用运行）。把 Folia 歌词动画播放器装到手机上，点开就是全屏歌词动画，登录态留在手机浏览器里，不用反复重新登录。核心界面还被 Service Worker（浏览器内置的离线缓存与自动更新机制）预缓存，断网也能快速启动看歌词。
💡 动手前先把两件事想明白
第一件：HTTPS 是 PWA 的硬门槛。HTTPS（带加密的网页协议）是浏览器认定的安全上下文，不升级它，PWA 就装不牢——安装入口可能不出现、离线启动失效、封面缓存降级。像http://NAS-IP:18080这种局域网 HTTP 地址就是典型。想让手机拿到完整体验，用 NAS 自带的反向代理加一张受信任证书把它升级成 HTTPS，现成的代理配置示例在 deploy/docker/README.md 的"HTTPS 与浏览器安全上下文"一节。
第二件：先认清手机端的能力边界。
- 离线能用：核心界面已预缓存，断网时快速启动、渲染歌词动画
- 联网才能用：音乐流、搜索、歌词匹配，听歌要等网络恢复
- 根本做不了：导入本地音频文件。本地导入依赖 File System Access API（浏览器读取本地文件夹的能力），目前只有桌面端 Chromium 系浏览器支持，HTTPS 也补不齐这块短板，手机端的"自己的歌"走 Navidrome 方案（下一节展开）
🚀 选一条路把 Folia 跑起来
- 免费托管一键部署——适合没有服务器的人
- 走仓库自带的 Vercel 或 Cloudflare 一键部署入口，几分钟拿到自带 HTTPS 的地址
- 若用平台内置的 QQ 音乐接口，
VITE_QQ_API_BASE填/api/qq即可，配置细节在 docs/qq-music-deployment.md
- NAS 上跑 Docker——适合家里有 NAS 的人
- 把
deploy/docker/compose.yaml与环境变量模板放进同一空目录，.env里填SYNC_TOKEN（可用openssl rand -hex 32生成） docker compose up -d启动，默认访问http://NAS-IP:18080，规则见 deploy/docker/README.md
- 把
- 克隆仓库自建——适合想自己掌控域名和密钥的人
git clone https://gitcode.com/GitHub_Trending/fo/folia-major- 按 docs/technical.md 的环境变量表部署到任意支持 Node.js 的平台
📱 主屏幕上见
地址就绪后，用手机浏览器打开它，再按机型走四步：
| 安卓（Chrome） | iPhone（Safari） |
|---|---|
| 1. 用 Chrome 打开 Folia 网页 | 1. 用 Safari 打开 Folia 网页 |
| 2. 点右上角菜单（⋮） | 2. 点底部分享按钮 |
| 3. 选"安装应用"或"添加到主屏幕" | 3. 上滑找到"添加到主屏幕" |
| 4. 确认名称为 Folia，点"添加" | 4. 确认名称，点"添加" |
装好后主屏幕多出 Folia 图标。点开的窗口没有地址栏、没有标签页，状态栏和应用融为一体——manifest（应用的元信息描述文件）里声明了standalone独立窗口模式，index.html也内置了apple-mobile-web-app-capable等元标签，所以 iPhone 和安卓的表现一致。
🎵 让音乐从自己的服务器流过来
曲库走 Navidrome，三步接入：
- 在 NAS 上用 Docker 部署 Navidrome（一个自托管的音乐库服务，把 NAS 上的音乐文件变成可远程访问的曲库），挂载你的音乐目录
- 在 Folia 的账户设置里填入 Navidrome 地址与账号
- Folia 拉取曲库、封面与歌词，歌词动画照常驱动
走 Docker 全栈部署的话，.env里再填NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项，新打开的浏览器会自动登录这个 Navidrome，手机不用单独输账号；改完后执行docker compose up -d --force-recreate backend生效，规则细节见 deploy/docker/README.md 的"Navidrome 预置账号"一节。
边界一句话：音乐文件留在 NAS，手机只负责播放，省流量也省空间，歌词还能智能匹配自动补齐。
✨ 打开后值得看的几个细节
先把边界钉死：界面离线能用，音乐流必须联网——Service Worker 已把核心界面资源预缓存，首次加载完成后启动不依赖实时网络；但歌曲音频要联网拉取，地铁里听歌得等网络恢复。
多风格全屏歌词动画主题。Folia 的招牌是多种风格的全屏歌词动画，每种主题有独立排版与可调参数，并随窗口尺寸响应式重排——竖着拿手机时，歌词布局自动重新排布，动画效果不打折。3D 轮播主题把封面转成一台唱片机：
群唱主题。歌词排成对话气泡，深色背景下读起来像一段群聊，手机竖屏上尤其耐看：
AI 自动配色。部署时配置了 AI 密钥的话（环境变量说明见 docs/technical.md），AI 会按歌曲情绪与歌词内容自动生成整组配色，手机上同样可用：
🛠️ 卡住了？对照这张表
| 现象 | 先查哪里 | 怎么办 |
|---|---|---|
| 找不到"安装应用 / 添加到主屏幕"入口 | 地址是不是 HTTPS；浏览器是不是 Chrome / Safari | 换成对应浏览器，重新加载页面再找菜单，安装提示有时只在首次访问出现 |
| 服务端已更新，手机上还是旧版 | PWA 走 autoUpdate（自动更新）策略，缓存异常会卡在旧版 | 正常打开一次等它生效；长时间不更新就清除该站点数据，或删掉 PWA 重新添加 |
| 找不到导入手机音频文件的入口 | 本地导入依赖 File System Access API，手机浏览器不支持 | 别在这条路上硬耗，手机端的"自己的歌"走 Navidrome 方案 |
| 地铁、弱网环境能不能用 | 核心界面已预缓存可离线启动，音乐流必须联网 | 弱网下可快速打开、看歌词动画；听歌等网络恢复 |
挑一条部署路径把 Folia 跑起来，再把地址加到手机主屏幕——点开那个图标，你的歌词动画播放器就随身了。
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
