Folia 手机端 PWA 完整指南：一键部署歌词动画播放器并装进手机主屏-育师

Folia 手机端 PWA 完整指南：一键部署歌词动画播放器并装进手机主屏

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

Folia 是一款主打全屏歌词动画的在线音乐播放器，支持网易云、QQ 音乐、酷狗与 Navidrome 曲库。本文带你把 Web 版一键部署上线，再装成 PWA 放进手机主屏，全程不需要写代码。

🧭 部署选型：Folia 歌词动画播放器的三条上线路线

先对号入座，选一条路线，后文主线跟着走。

路线 A：一键托管（没有服务器的人）适合第一次折腾。打开 Folia 项目页，点「Deploy with Vercel」或 Cloudflare 一键部署按钮，几分钟拿到 https 域名，证书和域名都不用管。QQ 音乐可以走 serverless 形态：把VITE_QQ_API_BASE填成/api/qq、再加一个服务端密钥即可，细节见 QQ 音乐部署指南。

路线 B：Docker 全栈（有 NAS 或服务器的人）适合已有 NAS 的用户，编排文件在 deploy/docker/compose.yaml。三步：编辑.env填入SYNC_TOKEN（至少 8 位随机字符串）→ 执行docker compose up -d→ 打开http://NAS-IP:18080。端口、反向代理、HTTPS 等细节见 Docker 部署说明。

路线 C：克隆仓库自行部署（想完全控制的人）环境变量、构建、HTTPS 全归自己管。克隆仓库后按技术与开发说明配置：

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

🚀 主线：Folia Web 一键部署上线并装进手机主屏

部署阶段：一键托管推上线

打开 Folia 项目页，点「Deploy with Vercel」一键部署按钮，用账号登录授权。
等云端构建结束，复制分配到的https://...域名，这就是你的 Folia 地址。
（可选）想启用 QQ 音乐：在部署平台的 env 里把VITE_QQ_API_BASE填成/api/qq，另加QQ_SESSION_SECRET（服务端密钥，不带VITE_前缀），重新部署。
走 Docker 路线的人，用上面路线 B 的三步替换第 1、2 步，地址是http://NAS-IP:18080。

验证做对了：浏览器打开这个域名，地址栏有锁标志，首页正常加载且能搜到歌曲。地址栏没锁就别往下走，先解决 HTTPS，否则手机装不了 PWA。

安装阶段：安卓 Chrome 添加到主屏幕

用Chrome打开 Folia 地址（其他浏览器可能没有安装入口）。
点右上角 ⋮ 菜单，选「安装应用」或「添加到主屏幕」。
确认名称为 Folia，点「添加」。

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

安装阶段：iPhone Safari 添加到主屏幕

用Safari打开同一个地址（必须是 Safari）。
点底部分享按钮，上滑找到「添加到主屏幕」，点击。
确认名称，点「添加」。

验证标准与安卓相同：启动即全屏独立窗口，看不到任何浏览器痕迹。

装好后搜一首歌播放。竖屏下全屏歌词动画完整可用，各主题排版自动适配手机屏幕，不裁剪也不拥挤。登录一次网易云、QQ 音乐或酷狗之后，登录态存在手机浏览器里，很长一段时间不用重复登。想换风格，走「主题速编」入口，风格和参数随时可调；AI 根据歌曲自动配色的前提是部署时配了 AI 密钥。

❓ 排错：Folia PWA 装不上、曲库连不上的高频问题

Q：浏览器菜单里找不到「添加到主屏幕」？A：原因二选一——访问的是 HTTP 地址，或没用 Chrome/Safari。换成 HTTPS 地址再重载一次页面，浏览器也换成指定款，入口就会出现。

Q：线上已更新，手机打开还是旧版界面？A：Service Worker 的自动更新策略一般下次打开才生效，偶尔会卡住。清除一次该站点的浏览器数据，或删掉图标重新添加到主屏即可。

Q：手机端为什么没有本地导入入口？A：本地目录导入依赖 File System Access API，只有桌面端 Chromium 系浏览器支持，手机端入口本身就不存在。要听「自己的歌」，走进阶一节的 Navidrome 路线。

Q：Navidrome 连上了，曲库和封面却拉不下来？A：多半是地址填了 Docker 内部主机名，手机根本够不到；或者页面是 HTTPS 而 Navidrome 是 HTTP，浏览器拦截混合内容。改成每台设备都可达的地址，需要时对齐到 HTTPS。

Q：HTTP 换成 HTTPS 之后，登录态和设置都没了？A：两个地址属于不同 origin，数据不会自动迁移。重新登录配置一遍；地址定型后就不要来回切换。

🗄️ 进阶：Folia Docker 部署 Navidrome 自建曲库

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

在 NAS 上用 Docker 部署 Navidrome，挂载你的音乐目录。
在 Folia 的账户页接入 Navidrome，地址必须是每台设备都够得到的地址；页面走 HTTPS 时它也得是 HTTPS。走 Docker 部署 Folia 的，可直接在.env填NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项，新打开的浏览器会自动登录。
曲库与封面同步完成后直接播放；缺失的歌词由智能匹配自动补齐，歌词动画照常驱动。

📌 边界：Folia 手机端能做什么、不能做什么

手机端不能导入手机本地的音频文件，本地目录导入只属于桌面端 Chromium 系浏览器；在线搜索播放、歌词动画、Navidrome 曲库、AI 主题配色均可正常使用。建议的上手顺序：先用一键托管把 Web 版跑起来，接一个在线曲库把歌词动画流程跑通，稳定之后再上 Navidrome 把「自己的歌」补进来。桌面端本地曲库的管理方式见本地曲库管理文档。

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