把 Folia 装进手机主屏幕：3 分钟完成 PWA 全屏歌词播放器

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

你正坐在地铁里，想接着听电脑上那首带歌词动画的歌，可手机浏览器打开 Folia 只是一个网页，地址栏、标签页一应俱全。好消息是：Folia 的 Web 版本身内置了 PWA（渐进式 Web 应用）能力，几下点击就能变成手机主屏幕上的独立图标，点开就是全屏窗口听歌，全程不需要应用商店的安装包。这篇文章覆盖从部署到安装的完整路径——已经有现成地址的话，3 分钟装完；连带部署，多留点时间。

动手前自检：HTTPS、浏览器、部署环境

• 部署方式想好：一键托管、NAS Docker、自部署三选一，目标只是拿到一个可访问的地址。
• 地址能上 HTTPS：PWA 的安装入口和离线缓存只在 HTTPS 安全上下文里可靠生效，裸 HTTP 装不上。
• 浏览器对齐：安卓用 Chrome，iOS 用 Safari，其他浏览器的安装入口可能不显示。
• 手机能连到部署地址：音乐流还是要走网络，NAS 部署的话，手机和 NAS 得在同一网络里。

⚠️ NAS 自部署如果没配反向代理并装上浏览器信任的证书，"安装应用"选项可能压根不会出现，自签名证书不算数。完整的反向代理配置，包括必须透传的头部清单，都在 deploy/docker/README.md 里。

部署 Folia 并装进手机主屏幕

1. 拿到地址。走 A 路：没有服务器，一键托管——点项目里的 Vercel / Cloudflare 一键部署，拿到带域名的地址，平台自带 HTTPS；想用 QQ 音乐的话，照 docs/qq-music-deployment.md 填环境变量即可。走 B 路：有 NAS，全栈部署——把 compose.yaml 和环境变量模板放进同一目录，用openssl rand -hex 32生成随机串填入SYNC_TOKEN，然后执行：

docker compose up -d

默认访问地址是http://NAS-IP:18080。deploy/docker/compose.yaml 里能看到全部六个服务：网关、backend、网易云/酷狗/QQ 音乐接口和 Sync Server，以及各自的默认端口。

2. 确认地址是 https。托管平台原生就是 https；NAS 必须过一遍反向代理。

⚠️ HTTP 和 HTTPS 在浏览器眼里是两个 origin：切换之后，旧地址下的登录态、曲库索引和设置不会自动迁移，要在新地址重新登录配置。

3. 安装。手机浏览器打开地址后：安卓点右上角菜单（⋮）→"添加到主屏幕"或"安装应用"→ 确认名称为 Folia；iOS点底部分享按钮 →"添加到主屏幕"。index.html 已带好 iOS 全屏元标签，两端拿到的是同一套独立窗口体验。

装进主屏幕之后：全屏歌词与主题切换

点图标，以 standalone 独立窗口启动——没有地址栏、没有标签页，观感接近原生应用。vite.config.ts 里的 PWA manifest 声明了display: 'standalone'和 512×512 图标，这就是独立窗口外观的来源。核心界面资源被 Service Worker 预缓存，冷启动明显快于普通网页；服务端更新后，下次打开自动切到新版，不用你手动清缓存。

在线曲库是手机端的主力用法：接入网易云、QQ 音乐、酷狗后，登录态留在手机浏览器里，搜索、播放、歌词动画全部照旧，部署好先在手机浏览器登录一次即可。

Folia 的拿手好戏是一整套全屏歌词动画主题，每个主题都有独立的排版氛围。手机竖屏下，版式跟随窗口尺寸自动重排，歌词重新组织，动画不打折。拿群唱主题举例：每句歌词排成聊天气泡，竖屏上观感更紧凑。想换风格不用翻设置，在播放界面直接进"主题速编"就行。

色板还有 AI 加持：主题配色会根据歌曲情绪和歌词内容自动推导，部署时配了 AI 密钥的话，手机端同样能用。

进阶：Navidrome 私有曲库接入

手机没有本地文件导入（那是桌面端 Chromium 浏览器的独占能力），想听"自己的歌"，官方路径是接 Navidrome：

1. NAS 上用 Docker 跑一个 Navidrome 实例，挂载音乐目录；
2. 在 Folia 的账户页填入 Navidrome 服务地址——或者在部署环境变量里填NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项，新浏览器会自动登录；
3. Folia 把曲库、封面、歌词一次拉齐，缺失的歌词还能走智能匹配自动补上。

歌安静地待在 NAS 上，手机不吃存储，也不怎么吃流量。

排障：安装翻车现象与解法速查

表里没覆盖的情况，先检查地址与 HTTPS，再检查浏览器与系统版本。

你刚刚完成了从"网页"到"主屏幕图标"的迁移：Folia PWA 已装好，全屏歌词随时能听。想继续深挖的话，主题清单、模块系统和在线音乐部署的细节都在 docs/technical.md 里。

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