Folia 歌词动画播放器装进手机：PWA 安装与自部署 30 分钟完整指南-开发者社区

Folia 歌词动画播放器装进手机：PWA 安装与自部署 30 分钟完整指南

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

昨晚地铁上，我用手机浏览器打开 Folia 地址，几步操作后，一个全屏歌词动画播放器就以独立图标躺在主屏上了。Folia 是一款支持网易云、QQ 音乐、酷狗、Navidrome 与本地曲库的多平台音乐播放器，招牌是全屏歌词动画。读完这篇，你能自己部署一个实例，并把它装进手机。

先搞懂原理：Folia 凭什么能装进手机主屏

Folia 的 Web 构建就是一个 PWA（渐进式 Web 应用）：vite.config.ts 里的 manifest 声明了standalone独立窗口模式，Service Worker 走autoUpdate策略；index.html内置了 iOS 全屏元标签。这意味着你不用经过任何应用商店，就能把这个"长得像 App 的网页"装到主屏，安装后核心界面资源由 Service Worker 预缓存，弱网下也能快速启动。

部署前 3 项必查条件

条件	为什么必须	自查方法
地址是 HTTPS	PWA 安装与离线运行依赖浏览器安全上下文，HTTP 下安装入口不出现	浏览器地址栏有锁形标识；NAS 自部署需反代加可信证书，见 deploy/docker/README.md 的 HTTPS 章节
安卓用 Chrome、iOS 用 Safari	其他浏览器不提供 PWA 安装入口	打开地址确认浏览器内核与版本
必填变量已填	Docker 全栈缺`SYNC_TOKEN`（至少八位随机串）会直接拒绝启动；AI 功能缺密钥则主题配色不可用	对照 deploy/docker/README.md 的环境变量表逐项核对

30 分钟把 Folia 上线：3 条部署路径

路径一：一键托管平台，零服务器

打开仓库 README.md，点 Vercel 或 Cloudflare 的一键部署按钮创建项目
部署完成后，在项目设置里补齐环境变量：音乐平台 API 地址、AI 提供商与密钥
变量清单与填写示例见 docs/technical.md 的部署与开发章节

几分钟拿到带域名、自带 HTTPS 的访问地址，全程不需要自己的服务器。

路径二：Docker 全栈，适合 NAS 自托管

新建空目录，放入 compose.yaml 与重命名为.env的 .env.example
编辑.env，给SYNC_TOKEN填入至少八位的随机字符串，AI 密钥可留空（不影响播放）
执行docker compose up -d，默认访问地址http://NAS-IP:18080

路径三：全量构建，自由度最高

克隆仓库：git clone https://gitcode.com/GitHub_Trending/fo/folia-major
确认本机 Node.js 为 24 或更高版本
按 docs/technical.md 的部署与开发章节安装依赖、配置环境变量并启动

适合想改代码、接自定义音源的用户。

手机安装 Folia PWA 的四步操作

Chrome 添加到主屏幕（安卓）

用 Chrome 打开 Folia 地址
点右上角菜单（⋮）
选"添加到主屏幕"或"安装应用"
确认名称为 Folia，点"添加"

Safari 添加到主屏幕（iPhone / iPad）

用 Safari 打开 Folia 地址
点底部分享按钮
上滑找到"添加到主屏幕"
确认名称，点"添加"

完成后主屏出现独立的 Folia 图标，点开直接全屏启动，没有地址栏，状态栏与应用背景融为一体，观感与原生 App 几乎一致。

手机端能力边界：什么支持，什么不支持

功能	手机 PWA	说明与替代
在线搜索与播放（网易云/QQ/酷狗）	✅ 支持	登录态保存在手机浏览器里
歌词动画主题	✅ 支持	布局随窗口尺寸响应式重排，竖屏照样完整
Navidrome 私有曲库	✅ 支持	支持服务器预置凭据自动登录
本地音乐文件夹导入	❌ 不支持	依赖 File System Access API，仅桌面 Chromium 系浏览器可用；替代方案：走 Navidrome
音频输出设备选择	⚠️ 降级	需要 HTTPS 安全上下文，详见 docs/local-library-management.md

进阶：Navidrome 凭据自动下发，手机听"自己的歌"

手机端导不了本地音频文件，让 Navidrome 补上这块：

在 NAS 上用 Docker 部署 Navidrome，挂载音乐目录
在.env填入NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项（NAVIDROME_URL必须是手机能直连的地址，不能写 Docker 内部主机名）
重建 backend 容器使配置生效

这套组合的好处：音乐文件留在 NAS，手机通过 PWA 远程访问，不占空间也不费流量；任何新打开的浏览器自动登录并启用 Navidrome，手机、电视、电脑不用再各登录一遍。

排错：6 个常见现象的自查方法

现象	原因	解决
菜单里找不到"添加到主屏幕"	地址不是 HTTPS，或浏览器不支持 PWA	改用 HTTPS 地址；安卓换 Chrome、iOS 换 Safari；重新加载页面，安装提示有时只在首次访问出现
更新后手机里还是旧界面	Service Worker 走`autoUpdate`，长时间未打开则未刷新	手动清除站点数据后重新添加；或等下次冷启动自动生效
QQ 音乐登录后曲库不可用	一键部署下`VITE_QQ_API_BASE`未填`/api/qq`，或缺`QQ_SESSION_SECRET`	按 docs/technical.md 补齐两项后重新部署
AI 主题配色不可用	部署时未配置 AI 密钥（如`GEMINI_API_KEY`）	补齐环境变量，重建对应容器或重新部署
Navidrome 预置凭据不生效	三项未填全，或`NAVIDROME_URL`不是完整 http(s) 地址、浏览器连不通	检查 backend 日志警告；换成各设备可达的地址后重建 backend
局域网 HTTP 下本地导入不可用	非安全上下文，File System Access API 被禁用	这是预期行为；手机听自己的歌走 Navidrome 方案