Folia 手机端完整指南：全屏歌词动画播放器用 Docker 部署并以 PWA 装入手机主屏

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

把 Folia 歌词动画播放器部署到手机够得到的地址，装进手机后当独立 App 使用，曲库来自在线平台或自建 Navidrome。

部署前准备清单：HTTPS、浏览器与曲库来源

以上三项缺哪项，就卡在对应那一环，先补齐再动手。

Docker 全栈部署：compose 文件加一条 up 命令

在 NAS 或服务器上，把仓库自带的 Compose 编排文件（描述整套容器服务如何启动的文件）拉下来即可，不要求下载整个源码：

1. mkdir folia-docker && cd folia-docker—— 建一个专用目录，之后所有文件都放这里。
2. curl -fL https://raw.githubusercontent.com/chthollyphile/folia-major/main/deploy/docker/compose.yaml -o compose.yaml—— 下载编排文件。
3. curl -fL https://raw.githubusercontent.com/chthollyphile/folia-major/main/deploy/docker/.env.example -o .env—— 下载环境变量模板并命名为.env。
4. openssl rand -hex 32—— 生成一串随机字符，把它填进.env的SYNC_TOKEN，这是同步服务要求的访问令牌，至少 8 位。
5. docker compose up -d—— 拉取镜像并在后台启动整套服务。
6. 浏览器打开http://NAS-IP:18080（把 NAS-IP 换成服务器实际地址），能看到 Folia 页面即成功。

其余路线各给一个指向：如果你不想维护服务器，就走 Vercel 一键托管，QQ 音乐在托管环境把VITE_QQ_API_BASE填成/api/qq并配一个服务端密钥即可，细节在 QQ 音乐部署指南。如果你要自己掌握环境变量、构建和 HTTPS，就执行git clone https://gitcode.com/GitHub_Trending/fo/folia-major克隆仓库后按 部署文档 自建。

手机安装与验证：安卓 Chrome 与 iOS Safari

安卓 Chrome 添加 Folia 主屏

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

启动后是独立全屏窗口，没有地址栏和标签页，说明装对了。

iPhone Safari 添加 Folia 主屏

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

图标从手机桌面启动后直接进入播放界面，看不到任何浏览器边框，就是装对了。

网易云、QQ 音乐、酷狗的登录态存在这台手机的浏览器里，登录一次长期有效。

接入自建曲库：歌曲存放、Navidrome 扫描与手机取用

文件流向是一条线：歌曲文件留在 NAS 或硬盘上，Navidrome 扫描目录后建立索引、对外提供流媒体接口，手机上的 Folia 只负责拉取歌曲列表、封面和歌词来驱动播放，不下载完整文件。

在 NAS 上用 Docker 部署 Navidrome 并挂载音乐目录后，到 Folia 的账户页填入它的地址与账号。地址必须每台设备都够得到，容器内部主机名手机访问不到，填了也连不上；协议要和 Folia 页面一致，页面走 HTTPS 时它也得是 HTTPS，否则浏览器拦截混合内容。

连接成功后曲库、封面和歌词随扫描结果同步过来，缺失歌词可以走智能匹配补齐，播放动画照常驱动。

出问题先查这张表

能力边界与上手顺序

手机端没有本地目录导入入口，它依赖只有桌面版浏览器才有的文件系统接口，想听自己的歌就接 Navidrome 补上。建议先走托管或 Docker 路线把地址跑起来，登录一个在线账号把歌词动画流程跑通，稳定之后再接入自建曲库。

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