3步把Folia歌词动画装进手机：免费部署+PWA安装完整指南-平芜编程栈

3步把Folia歌词动画装进手机：免费部署+PWA安装完整指南

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major

Folia 是一个主打全屏歌词动画的音乐播放器，曲库覆盖网易云音乐、QQ 音乐、酷狗与 Navidrome，这些动画在手机上能完整跑起来。本文帮你做完三件事：把 Web 版部署到手机能访问的地址、以 PWA（Progressive Web App，一种装进手机主屏的网页应用）的方式安装、再用 Navidrome 把自己的歌接进来。不需要服务器，也不需要 Docker 经验。

先弄懂：手机端能干什么、不能干什么

结论：手机上就是「歌词动画播放器 + 在线/Navidrome 曲库」，其余能力与桌面版一致。

各主题的排版会响应式自动适配竖屏，不裁剪也不拥挤，上面是真实渲染效果。能用的：在线搜索播放、歌词动画、Navidrome 曲库、主题速编（风格和参数随时可调），以及部署时配了 AI 密钥时的主题配色自动生成。不能用的：导入手机存储里的本地音频文件。原因写在明处——本地目录导入依赖 File System Access API（一套只被桌面端 Chromium 系浏览器支持的选目录接口），手机端没有这个能力，这部分留给桌面版做。

部署前的三道核验：地址、浏览器、预期

结论：地址不是 HTTPS，后面全部白费；这三道门先过，安装一次成型。

核验项	达标标准	不达标怎么办
访问地址	HTTPS，地址栏有锁标志	换免费托管平台，或给 NAS 配反向代理（替你终结 HTTPS 的转发层）与可信证书
手机浏览器	安卓用 Chrome，iOS 用 Safari	换对应浏览器再打开
功能预期	在线播放、歌词动画、Navidrome 可用；本地导入不可用	本地导入留给桌面版

三种一键部署方法：按你的条件挑一条

结论：先选对路线再动手，每条路线的细节都在部署文档里。

路线	适合谁	入口与关键命令
一键托管（Vercel / Cloudflare）	没有服务器，想几分钟上线	项目内置的一键部署按钮，自带 HTTPS 与域名
Docker 全栈	有 NAS 或自建服务器	编辑`.env`后执行`docker compose up -d`，默认地址`NAS-IP:18080`
克隆仓库自行部署	想完全控制环境变量	`git clone https://gitcode.com/GitHub_Trending/fo/folia-major`，再按部署文档配置

一键托管最省事，HTTPS 和域名都不用管。Docker 面向 NAS 用户，编排文件在 deploy/docker/compose.yaml，.env里要填一个至少 8 位的SYNC_TOKEN，缺了容器起不来。QQ 音乐的 serverless 配置另见 QQ 音乐部署指南。

手机安装 PWA 步骤：安卓与 iPhone 分开看

结论：部署完成后，用浏览器打开地址、添加到主屏即可；验证方式比步骤更重要。

安卓（Chrome）：

用 Chrome 打开 Folia 地址。
点右上角菜单（⋮）。
选「安装应用」或「添加到主屏幕」。
确认名称为 Folia，点添加。

iPhone（Safari）：

用 Safari 打开 Folia 地址。
点底部分享按钮。
上滑找到「添加到主屏幕」，点击。
确认名称，点添加。

验证装对了没有：点主屏图标，应用直接以独立全屏窗口启动，没有地址栏和标签页，就是装对了；iPhone 上状态栏与应用融为一体，看不到任何浏览器痕迹。

网易云、QQ 音乐、酷狗的登录态存在手机浏览器里，登录一次之后很长一段时间不用重复登。

进阶：用 Navidrome 在手机上听自己的歌

结论：文件留在 NAS，手机只拉流式播放，省空间也省流量。原理一句话：歌放在 NAS 上，Navidrome 扫描后以流媒体曲库对外服务，手机 PWA 只负责拉曲库、封面和歌词。

在 NAS 上用 Docker 部署 Navidrome，挂载你的音乐目录。
在 Folia 的账户页接入 Navidrome 服务。地址必须是每台设备都够得到的地址；Web 版走 HTTPS 时它也得是 HTTPS，否则浏览器会拦截混合内容（HTTPS 页面里出现的 HTTP 资源）。
曲库与封面同步完成后直接播放。缺失的歌词可以通过智能匹配自动补齐，歌词动画照常驱动。

桌面端本地曲库的管理方式可参考本地曲库管理文档。

常见故障排查：5 个高频问题对照表

结论：五个问题都只对应一类原因，按下表先对现象再动手。

现象	原因	处理
菜单里没有「添加到主屏幕」	访问的是 HTTP 地址，或没用 Chrome/Safari	换成 HTTPS 地址（免费托管自带；NAS 用户按 Docker 部署说明配反向代理与可信证书），再重载页面
更新后还是旧版本	Service Worker（浏览器里替网页做缓存更新的后台脚本）的 autoUpdate 一般下次打开才生效，偶尔卡住	清除一次站点数据，或删掉图标重新添加到主屏
手机端找不到本地导入入口	入口本来就不存在：File System Access API 仅桌面端 Chromium 系浏览器支持	「自己的歌」走 Navidrome 路线，本地导入留在桌面版
Navidrome 连上却加载失败	地址是 Docker 内部主机名手机够不到；或页面 HTTPS 而地址 HTTP	改成各设备可达的地址，需要时对齐到 HTTPS
换 HTTPS 后登录态消失	HTTP 与 HTTPS 属于不同 origin，数据不会自动迁移	重新登录并配置一遍；上线后不要来回切换地址