Folia 手机 PWA：从部署到独立应用安装的完整链路

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major

在地铁里点一下主屏幕上的 Folia 图标，打开的窗口没有地址栏、没有标签页，只有当前歌曲的歌词在深色画面上逐句流动——这就是 Folia PWA 手机安装完成后的样子：Web 版本身支持安装，地址加进主屏幕后它会以独立应用运行，登录态留在手机浏览器里。先交代一个术语：PWA 是可安装的网页，装好之后在手机上像独立应用一样运行。从仓库到主屏幕上那个图标之间，路径取决于手头有什么条件。

部署前先判断你属于哪种条件

把 Folia 发到手机上之前，先确认自己手上有什么：有（或愿意用）免费托管、只有 NAS、还是想克隆仓库自己掌控一切。三种条件的关键配置点差别不小。

走免费托管的话，仓库自带 Vercel 与 Cloudflare 两个一键部署入口，几分钟就能拿到自带 HTTPS 的地址。如果要用平台内置的 QQ 音乐接口，VITE_QQ_API_BASE填成/api/qq就行，这一项的部署细节写在 docs/qq-music-deployment.md 里。

只有 NAS 的话，走 Docker 全栈：把deploy/docker/compose.yaml和环境变量模板放进一个空目录，跑openssl rand -hex 32生成一段随机串贴进.env的SYNC_TOKEN，再执行docker compose up -d，容器起来后网关默认监听 18080 端口，访问地址就是http://NAS-IP:18080。

想完全自己掌控域名和密钥，就git clone https://gitcode.com/GitHub_Trending/fo/folia-major拉下仓库，环境变量的对照表写在 docs/technical.md 里，照着填、部署到任意支持 Node.js 的平台即可。

HTTP 地址为什么装不出完整 PWA

地址就绪之后，NAS 方案有一个容易踩的坑需要提前说清楚 ⚠️：http://NAS-IP:18080这种局域网 HTTP 地址，日常播放没问题，但普通 HTTP 不属于浏览器认定的安全上下文，负责离线缓存与后台更新的 Service Worker 无法可靠注册，PWA 的安装提示和离线能力都会跟着降级——最常见的症状就是菜单里找不到"安装应用"入口。

解决办法是让 NAS 自带的反向代理在前方终止 HTTPS，加一张浏览器信任的证书，把请求转发到http://127.0.0.1:18080。现成的代理配置示例、以及 HTTP 下会降级哪些能力，都写在 deploy/docker/README.md 的"HTTPS 与浏览器安全上下文"一节，照着配一遍就行。

安卓和 iPhone 的安装操作差异不大

HTTPS 就位后，手机端装起来反而简单。两个平台的差异其实集中在菜单位置：安卓上用 Chrome 打开 Folia 页面，从右上角 ⋮ 菜单里选"安装应用"或"添加到主屏幕"；iPhone 上用 Safari 打开，走底部分享按钮，上滑找到"添加到主屏幕"。两边确认名称为 Folia、添加即可，没有更深的讲究。

真正的验证信号在安装完成之后：主屏幕出现 Folia 图标，点开是独立窗口、无地址栏，状态栏与应用融为一体。这是因为 manifest 声明了standalone显示模式，index.html里也内置了apple-mobile-web-app-capable等元标签，所以 iPhone 和安卓两边的表现是一致的。

手机端曲库为什么必须走 Navidrome

"自己的歌"想在手机上放，推荐路径是 Navidrome（一个自托管的音乐库服务）：在 NAS 上用 Docker 部署它并挂载音乐目录，在 Folia 的账户设置里填 Navidrome 地址与账号，曲库、封面、歌词就会被拉取过来，歌词动画照常驱动。

那为什么不能在手机上直接导入本地音频？因为本地目录导入依赖 File System Access API，而这个能力目前只存在于桌面版 Chromium 系浏览器——通俗说就是手机浏览器根本没给应用留"选本地目录"这个入口，HTTPS 也补不齐这块短板。所以手机端把文件留在 NAS，通过 PWA 远程访问，是更省事的路线。

如果走的是 Docker 全栈部署，还可以在.env里补上NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项，改完跑docker compose up -d --force-recreate backend让后端重建，之后新打开的浏览器会自动登录这套 Navidrome 配置，手机不用单独输账号；这项预置账号的规则细节同样在 deploy/docker/README.md 的"Navidrome 预置账号"一节。

装好之后你会发现

用上一周，最先注意到的是响应式重排：竖着拿手机时，歌词布局会自动重新排布，每种主题有独立排版与可调参数，竖屏下动画效果并不打折。比如流光主题在深色屏幕上逐字晕开，群唱主题则把歌词排成对话气泡，读起来像一段群聊。

配色也不必全靠手动调：部署时配过 AI 密钥的话（说明在 docs/technical.md），AI 会按歌曲情绪与歌词内容自动生成整组配色，手机上同样可用。另外核心界面资源被 Service Worker 预缓存了，首次加载完成后，启动不依赖实时网络——地铁里能快速打开、看歌词动画；但音乐流本身必须联网拉取，离线听歌这一项等网络恢复才成立。

遇到问题先从这里查

如果你发现：找不到"安装应用 / 添加到主屏幕"入口

多半是地址还是 HTTP，或者浏览器不对。换用 Chrome 或 Safari，重新加载页面再找菜单——安装提示有时只在首次访问时出现，这不算异常。

如果你发现：服务端已更新，手机上还是旧版

PWA 用的是autoUpdate缓存策略，缓存异常时会卡在旧版。正常打开一次等它生效即可；长时间不更新的话，清除该站点数据，或删掉 PWA 重新添加。

如果你发现：弱网下界面完全打不开

理论上核心界面已预缓存、可以离线启动，打不开时优先回查地址是不是 HTTPS 安全上下文（见前述反向代理一节）。确认没问题的话，弱网下歌词动画可以照常看，听歌部分需要等网络恢复。

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major