Folia 手机端 PWA 部署教程：把全屏歌词动画装进手机主屏-开发者社区

Folia 手机端 PWA 部署教程：把全屏歌词动画装进手机主屏

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

你有一台 NAS 或闲置服务器，想让手机也跑全屏歌词动画。Folia 是一款主打歌词动画效果的音乐播放器，支持网易云、QQ 音乐、酷狗与 Navidrome 曲库。本文带你把 Web 版部署到手机可达的地址，装进主屏，再接入自己的曲库，全程不用写代码。

⚡ 先跑起来：选一条部署路径

选哪条路，取决于你手里有什么。

没有服务器，走一键托管。项目内置一键部署按钮，支持 Vercel 与 Cloudflare，点几下就能上线，HTTPS 和域名都由平台代管。QQ 音乐在托管环境能走 serverless 形态：把VITE_QQ_API_BASE配成/api/qq，再在服务端加一个会话密钥即可，完整步骤见 docs/qq-music-deployment.md。

有 NAS 或服务器，走 Docker 全栈。编排文件是 deploy/docker/compose.yaml。做法三步：编辑.env，给SYNC_TOKEN填一个至少 8 位的随机字符串（同步客户端的访问令牌）；执行docker compose up -d后台启动整套服务；浏览器打开http://NAS-IP:18080，把NAS-IP换成你的机器地址。端口与环境变量说明见 deploy/docker/README.md。

想完全控制，克隆仓库自行部署。环境变量、构建和 HTTPS 都归自己管：

git clone https://gitcode.com/GitHub_Trending/fo/folia-major

克隆下来后按 docs/technical.md 配置即可。

无论走哪条路，上线前先确认两件事。地址栏要有锁标志：PWA 安装入口依赖 HTTPS，纯 HTTP 会让安装按钮直接消失，NAS 场景可以套一层反向代理加可信证书。手机浏览器要选对：安卓用 Chrome，iOS 用 Safari，其他浏览器可能没有安装入口。

📱 装到主屏，然后打开就能听

部署完成后，剩下的动作都在手机上做。

安卓 Chrome 添加到主屏幕

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

iPhone Safari 添加到主屏幕

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

点主屏图标，应用以独立全屏窗口启动，没有地址栏和标签页，就是装对了。

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

进播放页就是全文的主角：全屏歌词动画。竖屏下各主题排版自适应，不裁剪也不拥挤。

想换风格，走「主题速编」入口，风格和参数随时可调。部署时配了 AI 密钥的话，主题配色还能根据歌曲自动生成。

🗄️ 自己的歌：接入 Navidrome 曲库

如果你不满足于在线曲库，想把 NAS 上自己的歌搬进手机，走 Navidrome。原理一句话：歌曲文件留在 NAS，Navidrome 扫描后以流媒体曲库对外服务，手机端 PWA 只负责拉取曲库、封面和歌词。这套组合省手机空间也省流量。

操作三步：

在 NAS 上用 Docker 部署 Navidrome，挂载你的音乐目录
在 Folia 账户页接入 Navidrome 服务，填上地址与账号
曲库与封面同步完成后直接播放，缺失的歌词可走智能匹配自动补齐

地址这一步最容易踩坑。填的地址必须是每台设备都够得到的地址：Navidrome 跑在 Docker 里时，容器内部主机名手机根本解析不到。协议也要对齐：Folia 页面走 HTTPS 时，Navidrome 地址也须是 HTTPS，否则浏览器会按混合内容（HTTPS 页面加载 HTTP 资源）拦截请求。

🔧 装不上、更新不了、连不上？对着查

找不到「添加到主屏幕」入口：多半是 HTTP 地址或浏览器不对，换 HTTPS 地址重载页面，浏览器换回 Chrome 或 Safari。
线上已更新，手机还是旧界面：Service Worker（浏览器内置的页面缓存与更新机制）没有刷新，清除该站点数据，或删掉图标重新添加。
Navidrome 连上了，曲库封面却拉不下来：多半填了 Docker 内部主机名，或页面 HTTPS 而地址是 HTTP，改成各设备可达的地址并对齐协议。
HTTP 换 HTTPS 后登录态设置都没了：两个地址属于不同 origin，数据不会自动迁移，重新登录配置一遍，地址定型后别再来回切换。
手机端没有本地导入入口：本地目录导入依赖 File System Access API（Chromium 桌面浏览器的本地文件访问接口），手机端入口本就不存在，想听自己的歌走 Navidrome。

手机端的能力上限摆在这里：在线播放、歌词动画、Navidrome 曲库都能用，导入手机本地音频文件不可用，那件事留给桌面版。建议先用一键托管把在线曲库跑通，把歌词动画流程走一遍；稳定之后再上 Navidrome，把「自己的歌」补进播放列表。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考