Folia PWA 手机端安装指南：3 步装好歌词动画播放器

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

Folia 歌词动画播放器可以以 PWA（渐进式 Web 应用）形式装到手机上：不用下载 App 安装包，把网页添加进主屏幕，就得到一个独立图标，点开即全屏听歌，服务端发版后客户端自动跟上。这篇指南讲清从部署到安装再到验收的完整路径。

一、安装前自检：三项前置条件

动手之前，花两分钟核对下表，缺任何一项后面的流程都会卡住：

为什么必须 HTTPS：浏览器的"安装为应用"与离线缓存，都只向安全上下文开放，协议不对，入口本身就不会生成。

二、获取访问地址：三档部署方案任选

PWA 的唯一前置，就是一个能访问的 Folia 地址。按你的条件挑一条路：

方案一：无服务器，一键托管

适合想最快跑起来的人。把仓库导入 Vercel / Cloudflare 这类平台即可拿到带域名的地址，平台直接提供 HTTPS，不用操心证书。用 QQ 音乐时，环境变量写法照 docs/qq-music-deployment.md 配置即可。

方案二：NAS 或自建服务器，Docker 全栈私有化

适合想整套自托管的人。将 deploy/docker/compose.yaml 与.env模板下载到同一目录，为SYNC_TOKEN写入至少 8 位随机串，再执行docker compose up -d，启动后默认访问地址是http://NAS-IP:18080。反向代理与完整配置说明见 deploy/docker/README.md。

方案三：逐条自定义，克隆仓库自部署

适合想逐项调整配置的人。执行git clone https://gitcode.com/GitHub_Trending/fo/folia-major取得源码，环境变量逐项说明看 docs/technical.md，任意支持 Node.js 的平台都能运行。

HTTPS 证书检查

⚠️ 菜单里的"添加应用"入口与离线缓存，是浏览器只授予安全上下文的能力，非 HTTPS 地址没有安装机会。免费托管平台会直接发好证书，无需处理；NAS 自建则需配置反向代理，装上浏览器信任的证书链——自签发的不被认可。若选项始终不出现，先怀疑证书。

地址就绪后，打开首页即是这样的界面：

三、双端安装对照：安卓添加主屏幕 vs iPhone 安装 PWA

两端都是三步，差别只在入口位置：

两处差异单独提醒：

• 入口形态不同：安卓藏在右上角菜单，iOS 藏在底部分享面板，图标与位置都不相同。
• 首次访问提示：安装提示有时只在首次访问时弹出，未出现的话重载一次页面再看；仍没有，通常是浏览器或地址没对齐，对照下面速查表排查。

四、装完验收：歌词动画、主题速编与自动更新

点图标进入的是一扇独立窗口：地址栏与标签栏消失，画面归播放器独占，体验贴近原生应用。这些行为在构建时即已声明——vite.config.ts 写明了display: 'standalone'窗口模式、#09090b主题色与 512×512 图标，index.html 则附带apple-mobile-web-app-capable一类的全屏元标签，因此安卓与 iPhone 各自拿到的都是同一套全屏表现。

可以逐项验收的核心体验：

• 竖屏版式自适应：歌词排版随窗口变化自动重组，竖着拿手机动画也不降质；每个全屏主题还各有独立的视觉氛围。
• 主题速编：切换风格不必翻设置层层找，"主题速编"入口直达。
• AI 推导色板：整组配色可以由 AI 按歌曲情绪与歌词内容推导，手机端同样可用——前提是部署时配置了 AI 密钥，实现位于 shared/ai/ 目录。
• 在线曲库如常：网易云、QQ 音乐、酷狗等登录态留在手机浏览器里，搜索、播放与歌词动画照旧，这是手机端的主力用法。
• 冷启动与自动更新：主界面资源在安装时已预缓存，图标启动比浏览器开页快不少；Service Worker 走autoUpdate策略，服务端发版后下次打开即切新版，无需手动清缓存。

比如群唱主题会把每句歌词放进气泡里，竖屏下的节奏更紧凑：

五、私有曲库选项：Navidrome 接入三步

手机端导入不了本地文件，家里的歌怎么办？官方路径是 Navidrome 私有曲库：

1. NAS 起服务：用 Docker 运行一个 Navidrome 实例，挂载音乐所在目录；
2. 账户页配置：在 Folia 的账户页填入该 Navidrome 地址，完成接入；
3. 数据对齐：曲库、封面与歌词会一并拉取，动画照常驱动，缺失部分由智能匹配自动补全。

文件始终留在 NAS，手机只通过网络取流播放，既不挤占存储，也不怎么耗流量。本地曲库管理的细节可参考 docs/local-library-management.md（该文档按桌面端导入流程撰写，接 Navidrome 的思路相通）。

六、排障速查表

七、收尾

整套流程就是配置、打开、安装。现在掏出手机试一次，看看歌词动画在主屏幕上的样子。

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