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

发布时间：2026/11/4 11:05:35
Folia 手机端完整指南：全屏歌词动画播放器用 Docker 部署并以 PWA 装入手机主屏

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

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

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

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

准备项要求缺了会怎样
访问地址HTTPS（浏览器安全上下文，部分网页能力只对可信地址开放）PWA 无法安装或不可靠，部分浏览器接口降级
手机浏览器安卓用 Chrome，iOS 用 Safari菜单里没有「添加到主屏幕」入口，装不了
曲库来源在线平台账号（网易云、QQ 音乐、酷狗）或自建 Navidrome（开源流媒体服务器，扫描本地音乐目录后供其他应用点播）应用能打开却没有可播内容

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

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，否则浏览器拦截混合内容。

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

出问题先查这张表

现象原因处理
菜单里没有「添加到主屏幕」访问的是 HTTP 地址，或没用 Chrome / Safari换 HTTPS 地址并换对应浏览器，重新加载
线上已更新，手机打开还是旧界面PWA 缓存策略导致，更新偶尔不生效清除该站点数据，或删掉图标重新添加
Navidrome 连上但拉不到歌曲与封面地址写成容器内部主机名，或协议与页面不一致改成各设备可达的地址，需要时对齐到 HTTPS
HTTP 换 HTTPS 后登录态与设置全丢两种协议属于不同源，数据不会迁移重新登录配置一遍，地址定型后别再切换

能力边界与上手顺序

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

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

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