Folia 歌词动画播放器如何装进手机主屏幕？PWA 部署完整指南

Folia 歌词动画播放器如何装进手机主屏幕？PWA 部署完整指南

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

一个网页未必只是个网页。Folia PWA 让你把歌词动画播放器的 Web 版直接「装」进手机，添加到主屏幕后，点一下图标就以全屏独立窗口启动。从拿到访问地址到看到歌词动画铺满整屏，全程不超过 10 分钟。

这篇写给谁

如果你已经在电脑上用 Folia，想让手机也打开同一套在线曲库和歌词动画，这篇带你把路走完。如果你的目标是往手机里导入本地音乐文件，请停在门外：这条路在手机上走不通，读完也不划算，文末最后一步给了替代方案。

先花 30 秒

先把一个概念说清楚，你才知道网页为什么能被装。PWA 是「可以装进手机的网页」：浏览器把它当原生应用对待，给独立图标、独立窗口，不再套着地址栏跑。Folia 的 Web 版原生支持这一套，manifest 与预缓存都已写进构建配置，部署时不需要再做任何额外动作。

第一步：拿到手机能打开的地址

先解决的是让 Folia 有一个手机打得开的地址。按你的条件对号入座：

• 一键部署：仓库提供指向 Vercel / Cloudflare 的部署按钮，不用自己的服务器，平台自带 HTTPS。接入 QQ 音乐参考 docs/qq-music-deployment.md。
• Docker 部署：把deploy/docker/compose.yaml与.env模板拷到目标机器，在.env填入SYNC_TOKEN（至少八位随机字符串），执行docker compose up -d。默认地址http://NAS-IP:18080，完整步骤见 deploy/docker/README.md。
• 自行部署：git clone https://gitcode.com/GitHub_Trending/fo/folia-major克隆仓库，按 docs/technical.md 的环境变量说明部署到任意支持 Node.js 的平台。

⚠️ HTTPS 是前提。PWA 要可靠安装、要离线运行，地址必须是 HTTPS。免费平台自带；NAS 自部署得配好反向代理和可信证书，否则手机上很可能看不到安装入口。

第二步：装进主屏幕

地址到手，接下来把 Folia 图标放进手机主屏幕。

安卓（用 Chrome）

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

iPhone / iPad（用 Safari）

1. 打开 Folia 网页
2. 点底部分享按钮（⬆️）
3. 上滑找到「添加到主屏幕」
4. 确认名称，点「添加」

装完，主屏幕多了一个独立的 Folia 图标。点它启动的是全屏独立窗口：没有地址栏，没有标签页，整块屏幕都属于歌词动画。

第三步：手机上能干嘛、不能干嘛

先把边界说清，装完再试会少走弯路。

✅ 完整支持

• 在线搜索与播放：网易云音乐、QQ 音乐、酷狗
• 歌词动画主题：响应式布局自动适配竖屏
• Navidrome 私有曲库

❌ 不支持

• 导入本地音乐文件：目录选择依赖桌面端的 File System Access API，手机浏览器没有选本地目录的能力

竖屏时，歌词排版会按窗口尺寸重新计算，动画不截断。流光（Lumière）在深色底上叠加流动光效、逐字入场；群唱（Cappella）把歌词排成对话气泡，多个人轮流「开口」。

体验接近原生，靠的是四个机制叠加：standalone显示模式、Service Worker 预缓存核心资源、autoUpdate自动更新、manifest 配置齐全——这些都写在 vite.config.ts 的 PWA manifest 里，index.html还内置了apple-mobile-web-app-capable等全屏元标签，安卓和 iPhone 拿到的是同一套体验。

第四步：听自己的歌

手机读不了本地音频文件，要补上「听自己的歌」这一环，走一条绕路。

1. NAS 上用 Docker 部署 Navidrome，挂载音乐目录
2. 在 Folia 的账户页接入 Navidrome 服务
3. Folia 拉取曲库、封面与歌词，动画照常驱动

音频文件始终留在 NAS，手机只是通过 PWA 远程播放的终端，不占手机存储。本地曲库的管理细节见 docs/local-library-management.md。

没跑通？对照排查

问题大多落在四种里，按顺序对。

现象：找不到「添加到主屏幕 / 安装应用」入口原因：地址不是 HTTPS，或浏览器不对解决：确认地址栏是 HTTPS；安卓用 Chrome、iOS 用 Safari；重新加载一次页面

现象：部署更新了，手机上还是旧版本原因：Service Worker 更新有延迟解决：autoUpdate策略下次打开即生效；长时间没变就清一次站点数据，或删掉图标重新添加

现象：想导入手机里的音乐文件原因：本地导入仅桌面端 Chromium 系浏览器可用解决：走第四步的 Navidrome 方案

现象：地铁 / 弱网里打不开原因：无解决：核心资源首次加载后已预缓存，弱网可快速启动；音乐流本身仍需网络

在线曲库、自己的歌、满屏歌词动画，往后都收进主屏幕同一个图标里，抬手就是。

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