Folia 装进手机主屏：PWA 部署与全屏歌词动画播放器配置教程
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
装完以后，手机主屏上会出现一个 Folia 图标，点它直接打开独立全屏窗口播放歌词动画。全文覆盖三件事：把 Folia Web 版部署上云、装成 PWA（把网页装成独立应用，有图标、无地址栏）、接入自建曲库。你需要准备的只有一台手机，和一个手机能访问到的 HTTPS Folia 地址。
手机端 Folia 能做与不能做的边界
先划功能边界。手机端形态是 Web 服务加 PWA，能做什么取决于浏览器允许做什么：
- 支持：在线曲库搜索与播放（网易云、QQ 音乐、酷狗）、全屏歌词动画、主题切换与快速主题编辑器、Navidrome 自建曲库。
- 不支持：手机导入本地音频目录。它依赖 File System Access API，这是一个让程序直接读取本地目录的浏览器能力，只有桌面 Chromium 系浏览器提供，手机上没有这个入口。
- 需额外配置：HTTPS 地址，是安装 PWA 的前置条件；AI 密钥，用于按歌曲生成主题配色，可选，部署时填入。
| 分组 | 功能 |
|---|---|
| 支持 | 在线歌曲搜索播放、全屏歌词动画、Navidrome 曲库、主题切换 |
| 不支持 | 手机本地音频导入、模组系统等桌面端专属功能 |
| 需额外配置 | HTTPS 地址、AI 密钥（可选） |
🧭 回答三个问题选部署路径
- 问题一：你有没有服务器或 NAS？没有，就只能选一键托管，域名和 HTTPS 由平台代管；有 NAS，可以按 deploy/docker/README.md 部署 Docker 全栈，数据留在自己机器上。
- 问题二：你愿不愿意自己管域名和 HTTPS？不愿意，就选一键托管，平台自动签发证书，地址天然带 HTTPS。
- 问题三：你需要 24 小时在线的固定地址吗？需要，一键托管或 NAS Docker 都满足；只是自己手机用，一键托管免费档就够。
答完三个问题，本文走唯一一条路：一键托管（Vercel 或 Cloudflare）。理由是不用提供服务器、不碰域名证书、几分钟内拿到访问地址。如果 NAS 上已经跑着 Docker，只把下一节换成 Docker 路线，其余步骤不变。
📱 一键托管部署 Folia 到手机可访问
- 打开仓库首页，点一键部署按钮，选 Vercel 或 Cloudflare，选择仓库后自动构建。成功标志：构建完成后拿到一个 https:// 开头的访问地址，说明服务已上线。
- 用浏览器打开该地址，确认页面正常加载。成功标志：Folia 首页出现且搜索框可用，说明部署就绪。
- 点页面顶部「账户」，登录网易云、QQ 音乐或酷狗任意一个；QQ 音乐的环境变量细节见 docs/qq-music-deployment.md。成功标志：首页出现该账户的歌单与推荐内容，说明登录完成。
- 搜索一首歌并播放，进入全屏视图看歌词动画。成功标志：全屏歌词居中显示、底部出现迷你播放条，说明手机端已具备完整使用条件。
安卓 Chrome 添加 PWA 到主屏的步骤
- 用 Chrome 打开 Folia 的 HTTPS 地址。
- 点屏幕右上角的三点菜单（⋮）。
- 点「安装应用」或「添加到主屏幕」。
- 确认名称为 Folia，点「添加」。
验证：点主屏上的新图标。如果弹出独立全屏窗口，没有地址栏和标签页，说明 PWA 安装完成；如果看到的是浏览器地址栏，说明没有加成应用，重做上面四步。
iPhone Safari 添加到主屏幕的步骤
- 用 Safari 打开 Folia 地址。
- 点屏幕底部的分享图标。
- 上滑找到「添加到主屏幕」，点它。
- 确认名称，点「添加」。
验证标准与安卓一致：点开图标后是独立全屏窗口，没有地址栏和标签页，即安装完成。登录态存在手机浏览器本地，登一次之后很长一段时间不用再登。
🔌 Navidrome 连接参数怎么填：三步把歌接到手机
原理一句话：歌留在 NAS 上，Navidrome（自托管的音乐曲库服务器）扫描目录后流式对外服务，手机端 PWA 只负责拉曲库、封面和歌词。
- 在 NAS 上用 Docker 部署 Navidrome，挂载音乐目录，等扫描完成。成功标志：Navidrome 自己的网页里能看到你的专辑和歌曲，说明曲库就绪。
- 打开 Folia 设置页，找到 Navidrome 连接设置，填服务器地址、用户名、密码，点测试。成功标志：测试显示成功即可保存；失败先检查地址格式和协议。
- 回到 Folia 首页，出现 Navidrome 页签，点进去播放自己的歌。成功标志：首页能看到自己的歌单与专辑，说明接入完成。
两条前置条件写清楚：地址要每台设备都够得到，不要填 Docker 内部主机名；Folia 页面是 HTTPS 时，Navidrome 地址也必须是 HTTPS，否则浏览器会拦截混合内容（HTTPS 页面加载 HTTP 资源）。缺歌词的歌可以走智能匹配自动补在线歌词，歌词动画照常驱动。
卡住先看这里
问：菜单里没有「添加到主屏幕」访问地址是 HTTP，或浏览器不是 Chrome / Safari，就会出现这种入口缺失。换成 HTTPS 地址和对应浏览器，重载页面再找。
问：部署更新后打开还是旧界面这是 Service Worker（负责把页面缓存在浏览器本地的组件）没有刷新缓存。清一次站点数据，或者删掉图标重新添加。
问：Navidrome 填了却连不上通常是地址其他设备够不到，或页面是 HTTPS 而地址是 HTTP。换成各设备可达的地址，并对齐协议。
问：切换 HTTPS 后登录态没了两个地址属于不同 origin，登录数据不迁移。重新登录并配置一遍，之后固定用一个地址，不再来回切换。
问：Docker 版启动后怎么确认起来了浏览器访问网关的健康检查入口，返回正常即服务在线：
http://服务器地址:18080/healthz
先做一键托管并接一个在线曲库，把搜索到全屏歌词动画这一整段流程用上一首真实歌曲；再上 Navidrome，把「自己的歌」补进手机；最后可以配置 AI 密钥让主题配色按歌曲自动生成，部署 sync-server 实现跨设备外观同步，细节见 docs/technical.md。
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
