Folia 手机 PWA 安装教程：3 步把全屏歌词动画放进手机主屏
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia 是一个以全屏沉浸式歌词动画为核心的音乐播放器，支持网易云、QQ 音乐、酷狗等在线曲库，也能接自己 NAS 上的 Navidrome。跟着这篇文章做完，你的安卓或 iPhone 主屏上会多出一个 Folia 图标，点它直接以独立全屏窗口开播歌词动画，看不到任何浏览器痕迹。
全程只需要一部手机和一个能在手机上打开的 Folia Web 地址，不用会写代码。唯一的硬性前提是地址必须走 HTTPS（地址栏带锁标志），否则浏览器不会提供「添加到主屏幕」入口。
📱 手机上的最终效果
歌词居中占满整屏，底部一条迷你播放条，各主题排版都会自适应竖屏，不会被裁掉。
想换风格，从首页设置入口切主题就行；当前歌曲的配色还能在快速主题编辑器里逐条微调，AI 按歌曲自动生成配色也走这个入口。
🔍 动手前：三项自检 + 选一条部署路线
先对着下面三行检查，再决定走哪条部署路线：
| 检查项 | 达标标准 | 不达标怎么办 |
|---|---|---|
| 访问地址 | HTTPS，地址栏有锁标志 | 用 Vercel / Cloudflare 免费托管，或给 NAS 配反向代理加可信证书 |
| 浏览器 | 安卓用 Chrome，iOS 用 Safari | 换成对应浏览器再打开 |
| 功能预期 | 在线搜索、播放、歌词动画、Navidrome 都可用 | 手机导入本地音频不支持，留给桌面端 |
最后一行是功能边界：本地目录导入依赖 File System Access API，只有桌面端 Chromium 系浏览器有这个能力，手机上没有对应入口，找不到的话不用找。
| 路线 | 适合谁 | 耗时 | 入口 |
|---|---|---|---|
| 一键托管（Vercel / Cloudflare） | 没服务器、想最快上线 | 几分钟 | 仓库首页的一键部署按钮 |
| Docker 全栈 | 有 NAS 或自建服务器 | 半小时左右 | deploy/docker/README.md |
| 克隆仓库自建 | 想完全控制环境变量 | 高，HTTPS 和变量都要自己管 | git clone https://gitcode.com/GitHub_Trending/fo/folia-major |
建议从一键托管开始，HTTPS 和域名平台都替你处理；NAS 用户直接上 Docker 全栈，QQ 音乐扫码登录在不同平台的差异可以看 docs/qq-music-deployment.md。
🚀 分步操作：从拿到地址到主屏图标
第一步 部署 Folia Web 版上线
- 在仓库首页点「Vercel 部署」或「Deploy to Cloudflare」按钮，选平台创建项目，等构建完成。
- 记下平台给你的访问地址，它默认就是 HTTPS。
- Docker 路线则在服务器上执行
docker compose up -d --wait，默认地址是http://服务器IP:18080。 - 浏览器访问
http://服务器IP:18080/healthz有正常返回，Docker 堆就算起好了。
第二步 打开页面登录并播放一首歌
- 手机浏览器打开 Folia 地址，点顶部的「账户」，登录网易云、QQ 音乐或酷狗任意一个。
- 搜索一首歌并播放，点开正在播放的歌曲，进入全屏歌词动画。
- 登录态存在手机浏览器本地，登一次之后很长一段时间不用再登。
第三步 安卓添加到主屏幕步骤
- 用 Chrome 打开 Folia 地址。
- 点右上角菜单（⋮）。
- 选「安装应用」或「添加到主屏幕」。
- 确认名称为 Folia，点添加。
验证点：点主屏图标直接以独立全屏窗口启动，没有地址栏和标签页，就算装对了。
第四步 iPhone Safari 安装 PWA 方法
- 用 Safari 打开 Folia 地址。
- 点底部分享按钮（向上箭头的方框）。
- 上滑找到「添加到主屏幕」，点击。
- 确认名称，点添加。
验证方式同安卓：启动即全屏独立模式，看不到任何浏览器痕迹。
第五步 进阶：接入 Navidrome 听自己的歌
原理一句话：歌留在 NAS 上，Navidrome 扫描后流式对外服务，手机上的 PWA 只负责拉曲库、封面和歌词。
- 在 NAS 上用 Docker 部署 Navidrome，挂载你的音乐目录。
- 打开 Folia 设置页，找到「Navidrome 服务器」连接设置，填服务器地址、用户名、密码，点「测试连接」通过后保存。
- 回首页，Navidrome 页签里出现你的歌单和专辑，直接播。
两个边界：地址必须是手机够得到的；Folia 页面走 HTTPS 时，Navidrome 地址也得是 HTTPS，否则浏览器会拦截混合内容。缺歌词的歌可以靠智能匹配自动补在线歌词，动画照常驱动。
⚠️ 卡住了？先查这张表
| 现象 | 原因 | 处理 |
|---|---|---|
| 菜单里没有「添加到主屏幕」 | 打开的是 HTTP 地址，或没用 Chrome / Safari | 换 HTTPS 地址，重载页面后再找入口 |
| 更新后打开还是旧界面 | Service Worker 缓存（浏览器自留的离线资源副本）卡住了旧文件 | 清一次站点数据，或删掉图标重新添加 |
| 找不到本地导入入口 | 功能边界：仅桌面端支持 | 本地导入留在桌面版，手机改走 Navidrome |
| Navidrome 填了却连不上 | 用了 Docker 内部主机名，或 HTTPS 页面填了 HTTP 地址 | 改成各设备可达的地址，并对齐 HTTPS |
| 换 HTTPS 后登录态没了 | 两个地址属于不同 origin（来源），数据不会迁移 | 重新登录和配置，之后别来回切换 |
登录态和设置都绑定在地址的「来源」上，域名一变，对浏览器来说就等于换了一台设备。
🧭 走通之后还能做什么
- 先把基本盘做稳：接一个在线曲库，把「搜索 → 播放 → 全屏歌词动画」完整操作一遍，熟悉手机上的操作手感。
- 接上 Navidrome 把自己的歌补进手机；Docker 部署支持在服务端预置 Navidrome 账号，局域网新设备打开即自动登录，变量见 deploy/docker/README.md。
- 想让主题配色按歌曲由 AI 自动生成，部署时配好 AI 密钥即可，各平台的配置差异见 docs/qq-music-deployment.md。
- 多台设备要同步外观和设置，再部署 sync-server，细节参考 docs/technical.md。
走通到这里，手机已经从「偶尔点开看看」变成一台正经的歌词动画播放器。
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
![可白嫖源码---课程设计--毕业设计--springboot医疗器械销售管理系统[编号：project15137]（案例分析）](http://pic.xiahunao.cn/yaotu/可白嫖源码---课程设计--毕业设计--springboot医疗器械销售管理系统[编号：project15137]（案例分析）)
