Folia 全屏歌词动画 PWA 手机安装完整指南：3 步把播放器装进主屏
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器 A multi-platform music player for local files, Navidrome, and online streaming services, featuring stunning animated lyrics.项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia 是一款以全屏歌词动画为核心的多平台音乐播放器，在线曲库、Navidrome、本地曲库都吃。装完之后你会得到什么？手机主屏上多出一个 Folia 图标，点一下直接进全屏歌词动画界面——没有地址栏，没有标签页，观感跟原生 App 一样。全程要做三件事：网页版上线、浏览器里出声、入口装进主屏，顺序别乱。
安装前先确认两件事：功能边界和 HTTPS
主屏安装之前，先把两个前提钉死。任何一个不过关，后面都是白忙。
手机端能做什么、做不了什么
| 手机端能用 | 手机端没有 |
|---|---|
| 在线搜索并播放 | 导入手机本地音频文件夹 |
| 全屏歌词动画 | — |
| Navidrome 曲库 | — |
本地导入为什么手机上没有？这功能依赖 File System Access API，只有桌面端的 Chromium 系浏览器提供，手机上压根不存在这个入口，别花时间找。想在手机上听自己硬盘里的歌，正路是 Navidrome，第四节专门讲。
浏览器也有讲究：安卓机固定用 Chrome，iPhone 固定用 Safari。其他浏览器要么没有「添加到主屏幕」这条路，要么行为不一致，装出来容易出问题。
地址栏有没有锁：HTTPS 判断 ⚠️
看浏览器地址栏的锁形标志，这是安装入口出现与否的开关：
- 走免费托管平台：平台自带 HTTPS，什么都不用管。
- NAS 自建：给反向代理挂一张可信证书，自签的不算数。
锁没有，PWA 安装入口根本不会出现，主屏这一步就别指望了。
Folia 最快上线方法：一键托管还是 Docker 全栈 🚀
两条路，按手头条件挑：
| 维度 | 路线 A：一键托管（Vercel / Cloudflare） | 路线 B：Docker 全栈（NAS / VPS） |
|---|---|---|
| 适合谁 | 没有服务器、只想最快上线的新手 | 有 NAS 或一台 VPS，想自己控制环境变量和版本 |
| 大概多久 | 几分钟 | 半小时左右 |
| 代价 | 几乎为零，HTTPS 和域名平台代管 | 要自己拉 compose 栈、配环境变量 |
路线 A直接用仓库首页的一键部署按钮创建项目，构建完拿到访问地址就完事，HTTPS 和域名都不用操心，新手首选。
路线 B拉完整 Web 堆栈，细节都写在 deploy/docker/README.md；如果只关心 QQ 音乐在 serverless 和常驻服务之间的登录方式差异，单独翻 docs/qq-music-deployment.md。
拿不准就走 A。跑通之后随时可以迁到 Docker，两条路不冲突。
Folia 手机主屏安装步骤：先从网页出声，再装进主屏幕
最小闭环：部署完怎么确认在出声
- 按上一节选好的路线把服务拉起来。
- 确认服务活着。Docker 路线在浏览器访问
http://服务器地址:18080/healthz，返回正常说明网关起来了；一键托管没有这一步，页面能打开、搜索有结果就算过。 - 打开页面，点顶部的「账户」，登录网易云、QQ 音乐或酷狗，挑一个就行。
- 搜一首歌，点播放，进全屏歌词动画。听到声音、歌词在动，主流程就跑通了。
登录态存在手机浏览器本地，登一次之后很长一段时间不用再登。
安卓主屏安装步骤：Chrome 添加到主屏幕
- 用 Chrome 打开 Folia 地址。
- 点右上角菜单（⋮）。
- 选「安装应用」或「添加到主屏幕」。
- 确认名称是 Folia，点添加。
验证：点主屏图标，直接弹出独立全屏窗口，界面上找不到地址栏、标签页和浏览器按钮 ✅ 对上了，就是装成了。
iPhone 主屏安装步骤：Safari 添加到主屏幕
- 用 Safari 打开 Folia 地址。
- 点底部分享按钮。
- 上滑找到「添加到主屏幕」，点它。
- 确认名称，点添加。
验证标准跟安卓一致：全屏独立模式，看不到任何浏览器痕迹，才算合格。
Navidrome 接入步骤：把 NAS 曲库流式推到手机 PWA 🎵
原理一句话：歌始终留在 NAS 上，Navidrome 扫描后对外流式服务；手机 PWA 只负责拉曲库、封面和歌词，音频本身不进手机。
- 在 NAS 上用 Docker 部署 Navidrome，把音乐目录挂进去。
- 打开 Folia 设置页，找到 Navidrome 连接设置，填服务器地址、用户名、密码，点测试，通过后保存。
- 回首页，Navidrome 页签下就是你的歌单和专辑，直接点着播。
接好之后首页长这样：
接对没有，看两点：
- Navidrome 地址必须是每台设备都够得到的。
- Folia 页面走 HTTPS 时，Navidrome 也得是 HTTPS，否则浏览器直接拦截混合内容。
个别歌缺歌词不用慌：智能匹配会自动补在线歌词，歌词动画照常驱动。
Folia 手机安装卡住了？三问自查加一张排查表 🔧
先问自己三句：入口找得到吗？连得上自己的曲库吗？打开的是新版界面吗？哪句答不上，对下表：
| 现象 | 多半原因 | 怎么办 |
|---|---|---|
| 菜单里翻不到「添加到主屏幕」 | 访问的是 HTTP 地址，或者用的不是 Chrome / Safari | 换 HTTPS 地址，重载页面后再找 |
| 找不到本地导入入口 | 功能边界，不是 bug，只有桌面端才有 | 手机这边走 Navidrome，见第四节 |
| 更新之后打开还是旧界面 | Service Worker 的缓存策略卡住了 | 清一次站点数据，或把图标删掉重新添加 |
| Navidrome 填了却连不上 | 写了 Docker 内部主机名，或页面 HTTPS 配了 HTTP 地址 | 改成各设备都可达的地址，必要时两边都统一到 HTTPS |
| 换到 HTTPS 之后登录态没了 | 两个地址属于不同 origin，数据本来就不迁移 | 重新登录、把配置补一遍，之后别来回切 |
之后更进一步：AI 自动配色与跨设备同步
跑通最小链路、接上 Navidrome 之后，还有两件锦上添花的事：
- AI 配色：部署时配了 AI 密钥，主题配色就能按当前歌曲自动生成，入口在首页设置里；快速主题编辑器还能把每个参数逐条调到位。
- 跨设备同步外观：部署 sync-server 即可，细节见 docs/technical.md。
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器 A multi-platform music player for local files, Navidrome, and online streaming services, featuring stunning animated lyrics.项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
