Folia PWA 教程：3 分钟把歌词动画播放器装进手机
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia 是一款主打绚丽歌词动画的本地音乐 / Navidrome / 在线多平台播放器。本文带你把 Folia Web 版部署上线，再把 Folia PWA 添加到手机主屏幕，3 分钟让安卓和 iPhone 获得接近原生 App 的全屏听歌体验。
先划清边界：手机端能做什么、不能做什么
给手机装 PWA 之前，先把能力边界说清楚，免得装完才发现缺了核心功能。
本地音乐目录导入不能在手机上用：它依赖桌面 Chromium 系浏览器独有的 File System Access API，手机浏览器根本没有这个能力。在线音乐源和 Navidrome 曲库则完全支持，登录态保存在手机浏览器里，歌词动画照常驱动，体验和桌面端基本一致。
| 能力 | 手机端 PWA | 说明 |
|---|---|---|
| 在线搜索与播放（网易云 / QQ / 酷狗） | ✅ 完全支持 | 登录态保存在手机浏览器 |
| 歌词动画主题 | ✅ 完全支持 | 响应式布局自动适配竖屏 |
| Navidrome 曲库 | ✅ 完全支持 | 家庭 NAS 曲库首选 |
| 本地音乐文件导入 | ❌ 不支持 | 依赖桌面端 File System Access API |
所以定位要摆正：手机上的 Folia 就是"歌词动画播放器 + 在线 / Navidrome 曲库"，把它当桌面版的完整平替反而会失望。
部署 Folia Web 版：三条路径按场景选
PWA 的本质是一个"可安装的网页"，前提是把 Folia Web 版放到手机能访问到的地址上。项目提供三条部署路径，按你的基础设施挑一条走。
用免费托管平台一键上线
最省事的方式：Vercel 或 Cloudflare 一键部署，几分钟拿到带域名的地址，不用自己的服务器，HTTPS 也自带。QQ 音乐相关的环境变量差异与排错方法写在 docs/qq-music-deployment.md，照抄即可。
在 NAS 上跑 Docker 全栈
已有 NAS 或自建服务器就走这条路，配合 Navidrome 正好组成"私有曲库 + 歌词动画"的完整方案：
- 新建空目录，下载 deploy/docker/compose.yaml 与环境变量模板
- 编辑
.env，填入SYNC_TOKEN等配置 - 一条命令启动：
docker compose up -d默认访问地址是http://NAS-IP:18080，端口、代理与健康检查的完整说明在 deploy/docker/README.md。
如果想完全自定义，克隆仓库后按 docs/technical.md 的环境变量说明部署到任意支持 Node.js 的平台：
git clone https://gitcode.com/GitHub_Trending/fo/folia-major安装入口找不到？先给 HTTPS 做一遍体检
先给结论：HTTP 访问下 PWA 无法可靠安装。局域网 IP 上的普通 HTTP 不属于浏览器安全上下文，Service Worker 注册会被拦截，离线缓存也就无从谈起。deploy/docker/README.md 的"HTTPS 与浏览器安全上下文"一节列了完整的降级清单，可以对照自查。
按你的部署方式对症处理：
- 免费托管平台：自带 HTTPS，这一节直接跳过
- NAS 自部署：让 NAS 现有反向代理（Caddy、Nginx Proxy Manager 等）终止 HTTPS 并签发可信证书
- 浏览器别用错：安卓用 Chrome，iOS 用 Safari，其他浏览器可能根本不显示安装入口
地址换好之后重新加载一次页面再找安装菜单——安装提示有时只在首次访问时出现，这不算 bug。
把 Folia PWA 装进手机主屏幕
安卓 Chrome 三步添加
- 用 Chrome 打开 Folia 地址
- 点右上角菜单（⋮），选"添加到主屏幕"或"安装应用"
- 确认名称后点击"添加"
iPhone Safari 两步添加
- 用 Safari 打开 Folia 地址，点底部分享按钮
- 上滑选"添加到主屏幕"，确认名称后点"添加"
完成后主屏幕上会出现 Folia 图标（manifest 里short_name就是 Folia）。点开之后应用以独立全屏窗口启动，没有地址栏和标签页，视觉上与原生 App 几乎无差别。这不是碰运气：vite.config.ts 的 manifest 声明了standalone显示模式、#09090b主题色和 512×512 图标；index.html 内置了apple-mobile-web-app-capable等元标签，iOS 状态栏样式也一并处理了。
验证全屏、离线与自动更新是否生效
装完顺手做三个检查，确认这套体验真的落地了，而不是"看起来像"。
检查一：全屏与竖屏适配。点开图标，确认没有浏览器地址栏和标签页；竖着拿手机时歌词布局会自动重排，动画完整度不打折。
检查二：弱网启动。核心界面资源已被 Service Worker 预缓存，首次加载完成后，地铁里打开也能快速进入界面。音乐流本身仍需网络，对通勤场景这点要有预期。
检查三：自动更新。Folia 的 Service Worker 采用autoUpdate注册策略（vite.config.ts），部署新版后下次打开自动生效。长时间停留在旧版时，清一次站点数据，或删掉图标重新添加到主屏幕即可。
主题速编入口里可以随时换风格：群唱、流光、倾诉这类主题各有独立的排版氛围和可调参数；部署时配置了 AI 密钥的话，配色还能按歌曲情绪与歌词内容自动生成，手机上同样可用。
接入 Navidrome，在手机上听 NAS 里的歌
手机上导不了本地音频，但"听自己的歌"这件事 Navidrome 能接住，三步走：
- 在 NAS 上用 Docker 部署 Navidrome，挂载音乐目录
- 在 Folia 的账户页接入 Navidrome 服务
- Folia 拉取曲库、封面与歌词，歌词动画照常驱动
这套组合的好处是音乐文件留在 NAS，手机只负责流式播放，省流量也省空间；歌词还能通过智能匹配自动补齐，管理细节看 docs/local-library-management.md。
一个容易踩坑的配置：NAVIDROME_URL要填各设备都能直连的地址，不能写 Docker 内部主机名；Folia 走 HTTPS 时 Navidrome 也必须是 HTTPS，否则浏览器会拦截混合内容。
行动清单：照做就能上线
- 部署 Folia Web 版到手机可访问的地址（免费托管或 Docker 全栈，约 5 分钟）
- 确认访问地址是 HTTPS，NAS 用户先配好反向代理与可信证书
- 安卓 Chrome 菜单 / iPhone Safari 分享 → 添加到主屏幕
- 点开 Folia 图标，对照"验证"一节的三项检查确认全屏、离线、自动更新生效
- 需要"自己的歌"时，再接入 Navidrome 曲库
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
