Folia 全屏歌词动画播放器手机端 PWA 快速安装完整指南
【免费下载链接】folia-major 专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器 
项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia 是一款以全屏歌词动画为核心的音乐播放器，支持在线曲库、Navidrome 和本地曲库，桌面端另有多种歌词动画主题与 AI 配色。跟着这篇指南走完，你的手机主屏上会出现一个 Folia 图标：点一下，直接进入全屏歌词动画播放界面，没有地址栏，没有标签页。整个过程分三步：把 Web 版部署上线，在浏览器里验证能搜能播，再把页面装进主屏。
一、先看看手机端跑起来是什么样子
装好之后，歌词居中铺满整块竖屏，底部只留一条迷你播放条。每个主题的排版都会响应式适配竖屏方向，不会出现被裁掉的情况。
想换风格不用折腾：首页的设置入口里可以切换主题，快速主题编辑器还能把每个参数逐条调到位。如果部署时配置了 AI 密钥，主题配色可以按当前歌曲自动生成，走的也是同一个入口。
二、开始之前先过三关
大多数人在手机上翻不到安装入口，根子都出在下面三点。逐项核一遍，后面基本不会再卡。
第一关：地址必须是 HTTPS。 看浏览器地址栏有没有锁形标志。没有的话，走免费托管平台最省事；NAS 自建的，给反向代理挂一张可信证书。这一关不过，PWA 安装入口根本不会出现。
第二关：浏览器选对。 安卓机用 Chrome，iPhone 用 Safari。其他浏览器要么没有「添加到主屏幕」这条路，要么行为不一致。
第三关：功能边界划清楚。
| 在线搜索并播放 | 导入手机本地音频文件夹 |
| 全屏歌词动画 | — |
| Navidrome 曲库 | — |
本地目录导入依赖 File System Access API，只有桌面端的 Chromium 系浏览器支持，手机上不存在这个入口，别花时间找。想在手机听自己硬盘里的歌，正路是 Navidrome，见第六节。
三、挑一条部署路线
两条路，按手头条件对号入座：
路线 A：一键托管（Vercel / Cloudflare） 适合没有服务器、只想最快上线的人。用仓库首页的一键部署按钮创建项目，构建完成后直接拿到访问地址，HTTPS 和域名都不用管。耗时几分钟，门槛最低，新手首选。
路线 B：Docker 全栈（NAS / 自建服务器） 适合有 NAS 或一台 VPS 的人。拉完整 Web 堆栈，自己控制环境变量和版本。耗时半小时左右，细节都在仓库的 deploy/docker/README.md 里；如果只关心 QQ 音乐在 serverless 和常驻服务之间的登录方式差异，再翻 docs/qq-music-deployment.md。
拿不准就走路线 A，跑通之后随时可以再迁到 Docker。
四、从部署到出声：四步走
登录态存在手机浏览器本地，登一次之后很长一段时间不用再登。
五、把 Folia 装进手机主屏
这一步把网页变成真正的独立应用。安卓和 iPhone 的菜单位置不一样，分开说。
安卓：Chrome 安装到主屏幕
一眼判断装对了没有：点主屏图标，直接弹出一个独立全屏窗口，界面上找不到地址栏、标签页和浏览器按钮——对，就是装成了。
iPhone：Safari 添加到主屏幕
同样看启动形态：全屏独立模式，看不到任何浏览器痕迹，才算合格。
六、接 Navidrome，把自己的歌搬上手机
原理一句话：歌始终留在 NAS 上，Navidrome 扫描后对外流式服务，手机 PWA 只负责拉曲库、封面和歌词，音频本身不进手机。
这里验证一下接对没有：Navidrome 地址必须是每台设备都够得到的；Folia 页面走 HTTPS 时，它也得是 HTTPS，否则浏览器直接拦截混合内容。个别歌缺歌词的话，智能匹配会自动补在线歌词，歌词动画照常驱动。
七、卡住了？对着这五个问自查
- 菜单里翻不到「添加到主屏幕」：九成是访问的是 HTTP 地址，或者用的不是 Chrome / Safari。换成 HTTPS 地址，重载页面后再找。
- 更新之后打开还是旧界面：Service Worker 的缓存策略偶尔会卡住。清一次站点数据，或者把图标删掉重新添加。
- 找不到本地导入入口：这是功能边界，不是 bug，桌面端才有。手机这边走 Navidrome。
- Navidrome 填了却连不上：多半是写了 Docker 内部主机名，或者页面 HTTPS 配了 HTTP 地址。改成各设备都可达的地址，必要时把两边都统一到 HTTPS。
- 换到 HTTPS 之后登录态没了：两个地址属于不同 origin，数据本来就不迁移。重新登录、把配置补一遍，之后别再来回切。
八、接下来往哪走
先按一键托管跑通：接一个在线曲库，把「搜索 → 播放 → 全屏歌词动画」这条最小链路完整走一遍。 稳了再上 Navidrome，把「自己的歌」补进手机。 最后两件事可以锦上添花：配 AI 密钥让主题配色按歌曲自动生成；需要跨设备同步外观时部署 sync-server，细节见 docs/technical.md。
【免费下载链接】folia-major 专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器 项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
