Folia PWA 安装指南：3 步把歌词动画播放器搬上手机
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia 是一款支持网易云、QQ、酷狗、Navidrome 的歌词动画播放器。它的 Web 版内置 PWA：手机浏览器里添加到主屏幕，就有独立图标和全屏窗口。部署加安装全程约 10 分钟。
🚀 路线选择：拿到手机可访问地址的 3 种方式
PWA 本质是带安装入口的网页，前提是先把 Web 版放到手机能访问的地址。三条路线，各有分工：
| 方式 | 适合谁 | 前置条件 | 耗时 |
|---|---|---|---|
| 一键托管 | 新手、无服务器 | 平台账号，HTTPS 自带 | 5~10 分钟 |
| Docker 全栈 | NAS / 自建用户 | Docker 24+、反向代理 | 15~30 分钟 |
| 克隆仓库自建 | 想完全自定义 | Node.js 24+、会配环境变量 | 30 分钟起 |
一句话推荐一键托管：平台直接给域名和 HTTPS，你只需补齐变量。Docker 路线把 compose 文件拷下来，填好 SYNC_TOKEN，再执行docker compose up -d。默认在 18080 端口提供访问。自建路线则先克隆仓库，填好 VITE_NETEASE_API_BASE 等变量再构建。
克隆命令是git clone https://gitcode.com/GitHub_Trending/fo/folia-major。变量全表见 docs/technical.md。
对手机端来说，路线只影响地址从哪来，后面的体验完全一致。
✅ 动手前检查：安装 Folia PWA 前确认的 3 件事
Folia 手机安装的流程不长，但有三个容易翻车的点。动手前先确认。
- 地址必须是 HTTPS。安装入口、离线缓存、音频设备枚举都依赖安全上下文。
- 用系统自带浏览器。安卓走 Chrome，iPhone 走 Safari，其他浏览器常不显示安装入口。
- 地址对手机可达。NAS 自部署时，确认手机与 NAS 同局域网，或已暴露公网地址。
地址栏不是 HTTPS 时，"添加到主屏幕"入口可能不出现，装上也跑不了离线。托管平台自带 HTTPS 最省心；自部署要给 NAS 配反向代理和可信证书。
这三项是安装的地基。缺一项，后面都会卡住。
📲 安装步骤：安卓与 iPhone 添加到主屏幕
地址打开后，两个系统各走 5 步。
安卓：Chrome 添加到主屏幕
- Chrome 打开 Folia 地址
- 点右上角三点菜单
- 选"添加到主屏幕"
- 确认名称与图标
- 点"添加"完成
iPhone：Safari 添加到主屏幕
- Safari 打开 Folia 地址
- 点底部分享按钮
- 上滑选"添加到主屏幕"
- 确认名称与图标
- 点"添加"完成
装好后点图标，会以独立全屏窗口启动，没有浏览器地址栏。顺手说下，确认弹窗里的名称与图标可以改，默认就是 Folia。路线不同，终点一致：主屏幕一个图标，全屏一个播放器。
🎨 效果呈现：Folia PWA 在手机上长什么样
连上网易云后，曲库首页是下面这样。卡片网格会按竖屏自动重排。
招牌是全屏歌词动画。每个主题都有独立排版，且随窗口尺寸响应式重排。竖着拿手机，歌词布局自动调整，动画照旧。pendolo 时计是机械齿轮风，cappella 群唱是左右对话气泡，lumi 流光在 OLED 屏上尤其好看。部署时配了密钥的话，配色还能由 AI 按歌曲情绪自动生成。
作为对照，本地曲库视图只有桌面版有。目录导入依赖 File System Access API，手机浏览器不具备这项能力，细节见 docs/local-library-management.md。
一句话，手机上拿的是"在线曲库 + 歌词动画"，唯一缺的就是目录导入。
| 能力 | 在 Folia PWA 手机端的结论 |
|---|---|
| 在线搜索与播放 | ✅ 支持 |
| 全屏歌词动画 | ✅ 支持，自动竖排重排 |
| Navidrome 私有曲库 | ✅ 支持 |
| 导入本地音乐文件 | ❌ 仅桌面端 |
📊 进阶玩法：接入 Navidrome 用手机听自己的歌
想听自己存的音乐？最顺的路是 Navidrome。文件放 NAS，手机走网络流播放，省空间也省流量。
前置条件：有 Docker 的 NAS，音乐文件已就位。
- NAS 上部署 Navidrome，挂载音乐目录
- 在 .env 填入 NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD 三项
- 重建 backend 容器
- 新打开的浏览器自动登录，曲库照常加载
接好后首页变成私有曲库视图：
注意预置只对新打开的浏览器生效。以前手动关过开关的，要到设置里自己打开。
Folia 走 HTTPS 时，NAVIDROME_URL 也要是 HTTPS。否则浏览器拦截混合内容，曲库加载不出来。
预置账号的完整说明在 deploy/docker/README.md 的"Navidrome 预置账号"一节。这一步做完，手机就成了随身私有曲库播放器。
🔧 排障：用户最常问的 4 个问题
Q：我按步骤走了，手机上没有"添加到主屏幕"，去哪找？先确认地址栏是 HTTPS，安卓用 Chrome、iPhone 用 Safari。安装提示有时只在首次访问出现，重新加载一次再试。
Q：部署了新版本，手机里还是旧界面，是不是翻车了？离线缓存由 Service Worker 管理，更新在下次冷启动生效。久不更新就清一次站点数据，或者卸载图标重新添加。
Q：手机能导入自己的音乐文件吗？电脑上明明可以。不能。目录导入依赖 File System Access API，只有桌面 Chromium 系有。手机想听自己的歌，走 Navidrome 方案。
Q：自部署后封面不缓存、输出设备也选不了？HTTP 不是安全上下文，Service Worker 与 OPFS 缓存都会降级。给 NAS 配好反向代理和可信证书，再重启 PWA 即可。
翻车时九成是安全上下文的问题，先看地址栏。
✅ 速查：3 分钟回顾安装 Folia PWA
| 步骤 | 操作 | 耗时 |
|---|---|---|
| 1 | 部署 Folia Web 版 | 约 5 分钟 |
| 2 | 手机浏览器打开地址 | 10 秒 |
| 3 | 菜单/分享，添加到主屏幕 | 1 分钟 |
| 4 | 点图标进入全屏 | 即时 |
一台手机，一台随身歌词动画播放器：在线搜索、Navidrome 私有曲库、全屏歌词动画，都装进 Folia PWA 的窗口里。
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
