如何在手机上安装 Folia：PWA 完整指南与避坑手册
【免费下载链接】folia-major 专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器 
项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia 是一款以绚丽歌词动画著称的沉浸式音乐播放器，支持网易云音乐、QQ 音乐、酷狗、Navidrome 与本地音乐库。它没有官方手机 App，但 Web 版原生支持 Folia PWA。读完这篇完整指南，你会知道如何把它装进手机主屏幕，并接上自己的 Navidrome 曲库。
一、先说结论：手机端 Folia PWA 能干什么
直接给答案：手机上把 Folia 当成"歌词动画播放器 + 在线/Navidrome 曲库"来用，体验完整；唯一缺的是直接导入手机本地文件。
手机端可以完整使用：
- 在线搜索与播放：网易云音乐、QQ 音乐、酷狗，登录态就保存在你手机的浏览器里
- 全部歌词动画主题：竖屏自动重新排版，动画效果不打折
- Navidrome 曲库：NAS 家庭曲库在手机上照常驱动歌词动画
手机端用不了：
- 本地音乐目录导入：依赖桌面浏览器的 File System Access API，手机浏览器不具备这项能力
为什么是 PWA 而不是别的方案？因为这套能力是仓库原生就写好的。vite.config.ts 里通过 VitePWA 插件注册了 Service Worker，registerType 设为 autoUpdate，构建后部署新版、下次打开自动生效；manifest 声明了 standalone 独立窗口模式、主题色 #09090b 与 512×512 应用图标。index.html 还内置了 apple-mobile-web-app-capable 等元标签，保证 iPhone 上同样以独立 App 窗口启动。安装后它拥有独立图标、全屏运行、核心界面离线可开——不需要任何安装包。
二、部署 Folia Web 版：30 秒选对方式
PWA 本质是"可安装的网页"，所以第一步是把 Folia Web 版部署到手机能访问的地址。按你的情况三选一：
新手：一键部署到免费托管平台
最省心的路径。用项目提供的一键部署入口（Vercel 或 Cloudflare），几分钟就能拿到一个自带 HTTPS 的访问地址，全程不需要自己的服务器。QQ 音乐在 serverless 形态下的配置方法（VITE_QQ_API_BASE 填 /api/qq 等）见 docs/qq-music-deployment.md。
NAS 用户：Docker 全栈部署
适合已有 NAS 或自建服务器的人。把 deploy/docker/compose.yaml 和环境变量模板放进一个空目录，编辑 .env 填入 SYNC_TOKEN 等配置，然后执行 docker compose up -d 启动。默认访问地址是 http://NAS-IP:18080。完整步骤与健康检查方法见 deploy/docker/README.md。
一个必须注意的点：http://NAS-IP:18080 这种局域网 HTTP 地址不属于浏览器安全上下文，Service Worker 与 PWA 在此状态下不能可靠安装、离线能力降级。想让手机获得完整的 PWA 体验，请用 NAS 自带的反向代理加一张受信任的证书把它升级为 HTTPS，文档里有现成的代理配置示例。
想完全自定义：克隆仓库自行部署
克隆仓库后（仓库地址：https://gitcode.com/GitHub_Trending/fo/folia-major），按照 docs/technical.md 的环境变量说明，部署到任意支持 Node.js 的平台。平台差异、域名与密钥全部自己掌控。
三、把 Folia 放进手机主屏幕
部署完成后，用手机浏览器打开你的 Folia 地址。
安卓：Chrome 安装 Folia PWA
iPhone：Safari 把 Folia 添加到主屏幕
完成后主屏幕会出现 Folia 图标。点开后它以独立 App 窗口启动，没有地址栏、没有标签页，状态栏与应用融为一体——视觉上和原生 App 几乎没差别。
四、打开之后：竖屏歌词动画与 AI 配色
Folia 的招牌是多种风格的全屏歌词动画主题，每种主题有独立的排版氛围与可调参数，并且会随窗口尺寸响应式重排。竖着拿手机时，歌词布局自动重新排布，动画效果不变。
深色背景搭配流动光效的"流光"风格，在 OLED 屏手机上尤其耐看：
主题配色不必全靠手动。如果部署时配置了 AI 密钥（环境变量说明见 docs/technical.md），就能让 AI 根据歌曲情绪与歌词内容自动生成整组主题配色，手机上同样可用。
五、Navidrome 接上"自己的曲库"
手机里存着几百首歌又导不进来？把音乐搬上 NAS，用 Navidrome 解决：
如果是走 Docker 全栈部署，还可以在 .env 里填好 NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD 三项，新打开的浏览器会自动登录 Navidrome，手机不用再单独输一遍账号。细节见 deploy/docker/README.md 的"Navidrome 预置账号"一节。
这套组合的好处：音乐文件留在 NAS，手机通过 PWA 远程访问，省流量也省空间，歌词还能智能匹配自动补齐。桌面端本地曲库的管理细节可参考 docs/local-library-management.md。
六、避坑手册：四个高频问题的排查顺序
现象：找不到"安装应用 / 添加到主屏幕"入口。 原因：PWA 的可靠安装依赖 HTTPS 安全上下文，HTTP 地址下浏览器通常不给出安装选项；另外部分浏览器干脆不提供这个入口。 解决：确认地址是 HTTPS；安卓只用 Chrome、iPhone 只用 Safari；必要时重新加载一次页面再找菜单，安装提示有时只在首次访问时出现。
现象：服务器上已更新，手机上打开还是旧版本。 原因：Service Worker 采用 autoUpdate 策略，正常情况下下次打开自动生效，但站点数据缓存异常时会卡在旧版。 解决：先等一次正常打开；长时间未更新就在浏览器里清除该站点数据，或删掉 PWA 重新添加到主屏幕。
现象：想在手机上导入手机里的音频文件，找不到入口。 原因：本地目录导入依赖 File System Access API，只有桌面 Chromium 系浏览器支持，手机浏览器没有这个能力。 解决：手机端的"自己的歌"走 Navidrome 方案（见上一节），不要在这条路上硬耗。
现象：地铁里、弱网环境能不能用？ 原因：核心界面资源已被 Service Worker 预缓存，界面启动不依赖实时网络；但音乐流本身必须联网拉取。 解决：首次加载完成后，弱网下也能快速启动应用、看歌词动画；听歌则需要网络恢复。
从部署到装进主屏幕，全程不过十来分钟。挑一个部署方式把 Folia 上线，剩下的事，交给手机主屏幕上那个黑色小图标——你的歌词动画播放器已经在口袋里了。
【免费下载链接】folia-major 专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器 项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
