Folia PWA 安装指南：3 分钟把歌词动画播放器装进手机主屏幕
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia 是一款专注歌词动画效果的本地音乐 / Navidrome / 多平台在线音乐播放器，没有官方手机 App，但 Web 版原生内置 PWA（Progressive Web App，渐进式 Web 应用）能力。按这篇指南操作，约 3 分钟就能让 Folia 以独立图标的形式出现在手机主屏幕上：部署一个手机够得到的 Web 地址，用 Chrome 或 Safari 把它「添加到主屏幕」，之后点开图标就是全屏播放界面，通勤路上在线搜歌、切主题看歌词动画、弱网环境离线秒开都能覆盖。
能做什么，边界在哪里
装好的 Folia PWA 覆盖这些日常场景：
- 在线搜索网易云、酷狗、QQ 音乐的歌，登录态存在手机浏览器里，不用每次重新登录
- 竖屏看全屏歌词动画，cappella、pendolo 等主题随窗口尺寸响应式重排
- 接上 Navidrome 后听 NAS 上的私有曲库，封面与歌词照常驱动
- 核心资源由 Service Worker（浏览器的离线缓存机制）预缓存，弱网打开速度明显快于普通网页
两条边界要说清：手机上不能导入本地音乐文件，目录导入依赖桌面浏览器的 File System Access API，手机浏览器没有这个能力，手机想听「自己的歌」走 Navidrome 路线；另外模组系统是桌面版专属，网页版和 PWA 里没有模组入口。
📋 动手前确认这五件事
| 前置条件 | 如何确认已满足 |
|---|---|
| 一台能上网的手机，安卓用 Chrome、iPhone 用 Safari | 打开浏览器能正常访问任意网站 |
| 一个手机能访问的 Folia Web 地址（托管平台域名，或 NAS 的局域网 IP + 端口） | 手机浏览器打开能看到 Folia 启动画面 |
| 地址是 HTTPS（托管平台自带；自部署需反向代理 + 可信证书） | 地址栏有锁形标识，不是http://开头 |
| Docker 路线：Docker Engine 24+ 与 Compose v2 | 终端执行docker version能看到输出 |
| 手机与 Folia 在同一网络（局域网部署时） | 手机浏览器能打开该地址 |
PWA 的安装入口和离线运行都依赖 HTTPS 安全上下文，这是后面所有步骤的前提。
🚦 部署路线怎么选
- 一键托管（Vercel / Cloudflare）：适合没有服务器的人。平台自带 HTTPS 和域名，导入仓库建项目即可，阻力最小。
- Docker 全栈：适合有 NAS 或自建服务器的用户，一套 compose 拉起前端网关、各音源接口和 Sync Server，但要自己配反向代理拿证书。
推荐新手走一键托管：HTTPS 这件最难的事平台免费解决。
🔧 主流程：从部署到主屏幕图标
第一步：把 Web 版部署到手机能打开的地址
托管路线：到 docs/technical.md 的「一键部署到 Vercel」一节按入口创建项目，然后在项目的环境变量里至少补上：
VITE_NETEASE_API_BASE=<你的网易云 API 实例地址> VITE_AI_PROVIDER=google GEMINI_API_KEY=<你的密钥>想开 QQ 音乐入口就再加VITE_QQ_API_BASE=/api/qq和QQ_SESSION_SECRET（不加VITE_前缀）。完成标志：重新部署后，手机浏览器打开分配的域名，能看到 Folia 启动动画和曲库首页。
Docker 路线：新建一个空目录，把仓库deploy/docker/下的compose.yaml和.env.example放进去（需要拉取源码时执行git clone https://gitcode.com/GitHub_Trending/fo/folia-major，从deploy/docker/目录取这两个文件），把.env.example改名为.env：
openssl rand -hex 32把输出填入.env的SYNC_TOKEN（必填，至少八位），然后：
docker compose up -d --wait docker compose ps完成标志：docker compose ps里所有容器都是 running 状态。在服务器上顺手验一下curl http://127.0.0.1:18080/healthz能返回健康结果。
注意：Docker 默认入口
http://NAS-IP:18080是普通 HTTP，不属于浏览器安全上下文，手机上会找不到安装入口。NAS 用户请在反向代理上挂可信证书，把域名指到127.0.0.1:18080，细节见 deploy/docker/README.md 的「HTTPS 与浏览器安全上下文」一节。
第二步：安卓安装到主屏幕
用 Chrome 打开 Folia 地址：
- 点右上角 ⋮ 菜单
- 选「添加到主屏幕」
- 确认名称显示为 Folia，点「添加」
完成标志：返回桌面出现 Folia 图标，点开以全屏独立窗口启动、没有地址栏——这是 manifest 里standalone显示模式生效的表现，也是判断装成功的直接证据。
第三步：iPhone 安装到主屏幕
用 Safari 打开 Folia 地址。仓库 index.html 已配好apple-mobile-web-app-capable等元标签，步骤：
- 点底部 ⬆️ 分享按钮
- 上滑找到「添加到主屏幕」
- 确认名称与图标，点「添加」
完成标志与安卓相同：桌面出现图标，点开为全屏窗口。连接网易云后，手机上看到的曲库首页长这样：
✅ 结果确认：全屏播放与离线启动
装上之后播放任意带歌词的歌，全屏歌词动画就是这台「手机 App」的核心证据。「cappella」主题把歌词排成左右交替的对话气泡，像一场合唱推进，竖屏窄屏下依然好读：
「pendolo」主题是机械齿轮与星空轨道，副歌高亮逐字亮起。动画帧率正常、无掉帧，说明 Service Worker 缓存与渲染都在正常工作：
另外两个正常信号：完全断网后重新打开图标仍能进入应用（核心资源命中预缓存）；服务器发新版后，完全关闭图标再打开才会加载新版本——Service Worker 用的是autoUpdate策略，更新在下一次冷启动才生效。
🎛️ 进阶：Navidrome 预置账号，手机免登录听私有曲库
想让 NAS 上的歌出现在 PWA 里，三步完成：
- 在 NAS 上用 Docker 部署 Navidrome，挂载音乐目录
- 在 Folia 的
.env（Docker 路线）或托管平台环境变量里填入NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项 - 手机新打开一次浏览器，Folia 会自动登录并启用 Navidrome，无需手动填账号
注意：
NAVIDROME_URL必须是各设备都能访问到的地址，不能写 Docker 内部主机名；Folia 走 HTTPS 时它也要是 HTTPS，否则浏览器会拦截混合内容。三项只填一两项时预置不生效，backend 日志会报警告。
配置生效后，PWA 首页就是这样的私有曲库视图：
⚠️ 排障速查
装不上或用起来有怪象时，按出现概率从高到低对照：
| 现象 | 常见原因 | 对应处理 |
|---|---|---|
| 浏览器里找不到「添加到主屏幕」 | 地址是 HTTP，非安全上下文；或用了非 Chrome / Safari 的浏览器 | 确认地址栏是 HTTPS；换 Chrome（安卓）或 Safari（iOS）；重新加载页面再试 |
| 服务端更新了，手机还是旧版本 | autoUpdate策略下更新只在下次冷启动生效 | 完全关闭应用后重新打开；长期不更新则清除站点数据，卸载图标重新添加 |
| HTTPS 下封面不缓存、选不了音频输出设备 | 证书链不完整（自签名证书不算），OPFS 与设备枚举被降级 | 查看证书详情确认链完整，换可信证书后重启 PWA |
| 填了 Navidrome 三项变量，手机端没自动登录 | NAVIDROME_URL手机访问不到、被混合内容拦截；或该浏览器曾手动关过 Navidrome 开关 | 用同一网络的手机直接打开NAVIDROME_URL验证连通性；在设置里手动打开 Navidrome 开关 |
部署加安装一共 3 分钟，手机主屏幕上就多了一台全屏歌词动画播放器：在线搜索、Navidrome 曲库、离线秒开都在这个图标里。部署细节与音源配置随时回看 deploy/docker/README.md 和 docs/technical.md。
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
