Folia 全屏歌词动画手机端 PWA 安装完整指南
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器 A multi-platform music player for local files, Navidrome, and online streaming services, featuring stunning animated lyrics.项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia 是围绕全屏歌词动画做的音乐播放器。本篇带你走通把 Folia 作为 PWA 装进手机主屏的全流程：点图标即进全屏歌词播放，无地址栏、无标签页。路径分三段：部署、浏览器验证、装进主屏。
歌词居中铺满竖屏，底部只留一条迷你播放条，每个主题的排版都响应式适配竖屏。首页设置入口能切换主题，快速主题编辑器可以把每个参数逐条调到位；桌面端还有更多歌词动画主题可选，配置了 AI 密钥时，主题配色会按当前歌曲自动生成。
开始前三项自查：地址、浏览器、功能边界
| 检查项 | 怎么判断 | 不通过怎么办 |
|---|---|---|
| 地址协议 | 地址栏有锁形标志，就是 HTTPS | 免费托管平台最省事；NAS 自建给反向代理挂一张可信证书。这一条不过，PWA 安装入口根本不会出现 |
| 浏览器选择 | 安卓用Chrome，iPhone 用Safari | 其他浏览器要么没有「添加到主屏幕」入口，要么行为不一致，换成上面这两个 |
| 功能边界 | 手机端有在线搜索播放、全屏歌词动画、Navidrome 曲库 | 本地文件夹导入仅桌面端：依赖 File System Access API，只有桌面 Chromium 系浏览器有，这是边界不是 bug；手机本地音乐走 Navidrome |
两条部署路线，按条件二选一
| 路线 | 适合谁 | 耗时 | 拿到什么 |
|---|---|---|---|
| 路线 A：Vercel / Cloudflare 一键托管 | 没有服务器、想最快上线 | 几分钟 | 访问地址，HTTPS 与域名自动处理 |
| 路线 B：Docker 全栈 | 有 NAS 或 VPS 的人 | 约半小时 | 完整 Web 堆栈，环境变量与版本自控 |
路线 A 用仓库首页的一键部署按钮创建项目，构建结束直接拿地址，首次上线最省事。路线 B 自己拉起 compose 栈，细节在 deploy/docker/README.md；QQ 音乐登录方式在 serverless 与常驻服务之间的差异，看 docs/qq-music-deployment.md。拿不准就先走低门槛路线，跑通之后随时可迁 Docker。
从部署到主屏：五个步骤走完全流程
- 部署。按选定路线执行：路线 A 等构建结束，路线 B 按部署文档拉起 compose 栈。
- 验证服务活着。Docker 路线在浏览器访问
http://服务器地址:18080/healthz，返回正常说明网关已起；一键托管只需页面能打开、搜索有结果。 - 登录。点顶部账户，登录网易云、QQ 音乐、酷狗中的任意一个。
- 搜索并播放。挑一首歌，点播放进入全屏歌词动画——听到声音、歌词在动，这步就算过。
- 装进主屏幕。
- 安卓：Chrome 打开 Folia 地址 → 右上角菜单（⋮）→安装应用或添加到主屏幕→ 确认名称是 Folia。
- iPhone：Safari 打开 Folia 地址 → 底部分享按钮 →添加到主屏幕→ 确认名称。
共同合格线：点主屏图标会弹出独立全屏窗口，看不到地址栏、标签页和浏览器按钮，才算装成。登录态存在手机浏览器本地，登一次长期有效。
接入 Navidrome，把硬盘里的歌搬上手机
一句话原理：歌曲始终留在 NAS 上，Navidrome 扫描后对外流式服务，手机 PWA 只拉曲库、封面和歌词，音频本身不进手机。
- 在 NAS 上用 Docker 部署 Navidrome，把你的音乐目录挂进去。
- 打开 Folia 设置页，找到 Navidrome 连接设置，填服务器地址、用户名、密码，点测试，通过后保存。
- 回首页，Navidrome 页签下就是你的歌单和专辑，直接点着播。
验证清单：
- 地址必须是每台设备都够得到的；
- Folia 页面走 HTTPS 时，Navidrome 也须 HTTPS，否则混合内容会被浏览器拦截；
- 个别歌缺歌词会智能匹配在线歌词，动画照常驱动。
五个高频坑，对照表格自查
| 现象 | 大概率原因 | 一句处理 |
|---|---|---|
| 菜单翻不到「添加到主屏幕」 | HTTP 地址，或浏览器不是 Chrome / Safari | 换成 HTTPS 地址，重载页面再找 |
| 更新之后打开还是旧界面 | Service Worker 缓存卡住 | 清一次站点数据，或删图标重新添加 |
| 找不到本地导入入口 | 功能边界，不是 bug，仅桌面端有 | 手机这边走 Navidrome |
| Navidrome 填了却连不上 | 写了 Docker 内部主机名，或 HTTPS 页面配了 HTTP 地址 | 改成各设备可达的地址，两边统一 HTTPS |
| 换到 HTTPS 之后登录态没了 | 两个地址是不同 origin，数据本就不迁移 | 重新登录并补一遍配置，之后别来回切 |
接下来三步：最小链路 → 自己的歌 → 锦上添花
先用一键托管加一个在线曲库，把「搜索 → 播放 → 全屏歌词动画」最小链路完整跑一遍。再接 Navidrome，把「自己的歌」搬上手机。最后两件事锦上添花：配 AI 密钥让主题配色按歌生成；需要跨设备同步外观时部署 sync-server，细节见 docs/technical.md。
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器 A multi-platform music player for local files, Navidrome, and online streaming services, featuring stunning animated lyrics.项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
