Folia 手机 PWA 安装指南：四步把歌词动画播放器装进手机
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia 是一个主打歌词动画的本地音乐 / Navidrome / 在线多平台播放器。这篇教程带你走完整条 Folia 手机 PWA 安装路径：选部署路线、拿到地址、装进主屏幕，再连上自己的曲库。
装好长什么样
安装完成后，主屏幕多一个 Folia 图标，点开的窗口没有地址栏、没有标签页，状态栏和应用融为一体，观感跟原生 App 没区别。界面布局还会随窗口尺寸响应式重排，竖着拿手机时歌词自动重新排布，动画效果不打折。
一键拿到能访问的地址
PWA（可安装成 App 的网页）本质还是网页，前提是手机先连得上它。三条路线按自己的情况挑：
| 路线 | 适合谁 | 能拿到什么 |
|---|---|---|
| 免费托管，一键部署 | 没有服务器，想几分钟上线 | 自带 HTTPS 的地址，全程不用自己的服务器；用平台内置 QQ 音乐接口时VITE_QQ_API_BASE填/api/qq即可，细节见 docs/qq-music-deployment.md |
| NAS 上 Docker | 有 NAS，想自己掌控 | 空目录里放好compose.yaml与.env模板，填SYNC_TOKEN（openssl rand -hex 32生成），跑docker compose up -d --wait，默认访问http://NAS-IP:18080，流程见 deploy/docker/README.md |
| 克隆仓库自建 | 域名与密钥全想自己掌控 | git clone https://gitcode.com/GitHub_Trending/fo/folia-major，按 docs/technical.md 的环境变量说明部署到任意支持 Node.js 的平台 |
地址务必是 HTTPS，这不是走过场。局域网 IP 上的普通 HTTP 不属于浏览器安全上下文，Service Worker（浏览器里的离线缓存与后台更新机制）装不牢，PWA 安装入口和离线能力都会降级。解决办法是让 NAS 自带反向代理加一张受信任证书把 HTTPS 终止掉，现成代理配置示例在 deploy/docker/README.md 的"HTTPS 与浏览器安全上下文"一节。
Folia 添加到主屏幕：安卓 Chrome 四步安装
- 用 Chrome 打开 Folia 网页
- 点右上角菜单（⋮）
- 选"安装应用"或"添加到主屏幕"
- 确认名称是 Folia，点"添加"
Folia 添加到主屏幕：iPhone Safari
- 用 Safari 打开 Folia 网页
- 点底部分享按钮
- 上滑找到"添加到主屏幕"
- 确认名称，点"添加"
双端装完表现一致是有技术原因的：manifest 声明了standalone独立窗口模式，index.html 也内置了apple-mobile-web-app-capable等元标签，安卓和 iPhone 都不需要额外配置。
Folia 连接 Navidrome：播放自己的歌
曲库走 Navidrome（一个自托管的音乐库服务），接入三步：
- 在 NAS 上用 Docker 部署 Navidrome，挂载你的音乐目录
- 在 Folia 的账户设置里填入 Navidrome 地址与账号
- Folia 拉取曲库、封面与歌词，歌词动画照常驱动
走 Docker 全栈部署的话，.env里再补NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项，之后新打开的浏览器会自动登录这个 Navidrome，手机不用单独输账号；改完执行docker compose up -d --force-recreate backend生效，规则细节看 deploy/docker/README.md 的"Navidrome 预置账号"一节。
这里提前说清一个边界：手机浏览器导入不了本地音频文件。本地目录导入依赖 File System Access API，目前只有桌面端 Chromium 系浏览器支持，HTTPS 也补不齐这块短板。所以手机端的"自己的歌"直接走 Navidrome 路线：音乐文件留在 NAS，手机通过 PWA 远程访问，省流量也省空间，歌词还能智能匹配自动补齐。
出问题先自查
| 现象 | 先查什么 | 怎么办 |
|---|---|---|
| 找不到"安装应用 / 添加到主屏幕"入口 | 地址是不是 HTTPS；浏览器是不是 Chrome / Safari | 换成对应浏览器；安装提示有时只在首次访问出现，重新加载页面再找菜单 |
| 服务端已更新，手机上还是旧版 | PWA 用autoUpdate策略，缓存异常会卡旧版 | 正常打开一次等它生效；长时间不更新就清除该站点数据，或删掉 PWA 重新添加 |
| 找不到导入手机音频文件的入口 | 本地导入依赖 File System Access API，手机浏览器不支持 | 别在这条路上硬耗，手机端的"自己的歌"走 Navidrome 方案 |
| 地铁、弱网环境能不能用 | 核心界面已预缓存可离线启动，音乐流必须联网 | 弱网下可快速打开、看歌词动画；听歌需等网络恢复 |
挑一条部署路线把 Folia 上线，再把地址加到主屏幕——手机上那个新图标，就是你的歌词动画播放器。
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
