免费快速完整指南：5 分钟把 Folia 歌词动画播放器装进手机（PWA 教程）

免费快速完整指南：5 分钟把 Folia 歌词动画播放器装进手机（PWA 教程）

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

Folia 没有官方手机 App，但 Web 版是标准 PWA（渐进式 Web 应用，装进手机就像 App 的网页）。按本文操作，约 5 分钟就能把这套歌词动画播放器装进手机主屏，全程免下载。

🎁 装完之后你能得到什么

先看效果再动手，把结果摆在你面前。

装完以后，你的手机主屏上会多出一个 Folia 独立图标。点开的瞬间没有地址栏、没有标签页，整块屏幕被歌词动画接管。网易云音乐、QQ 音乐、酷狗、Navidrome，全部接得上，播放时歌词随旋律整屏动。

手机端能力边界一张表，照表对号入座：

功能	能否使用	一句话解释
在线搜索播放	可以	网易云、QQ 音乐、酷狗登录态留在手机浏览器里
歌词动画主题	可以	响应式布局自动适配手机竖屏
Navidrome 曲库	可以	NAS 上的歌通过 PWA 远程播
导入本地音乐文件	不行	依赖桌面浏览器 File System Access API（目录选择能力），手机浏览器没有

🗺️ 第一步：拿到一个手机能打开的地址

记住一句话：PWA 装得稳不稳，全看地址是 HTTPS 还是 HTTP。三种路线，按你的情况选一种：

路线	适合谁	耗时
免费托管平台一键部署（Vercel / Cloudflare）	没有服务器的新手	约 5 分钟
Docker 全栈部署	有 NAS 或自建服务器	几步配置
克隆仓库自行部署	想完全自定义	看目标环境

新手路线：免费托管平台一键部署（Vercel / Cloudflare）

项目提供一键部署入口，指向 Vercel 或 Cloudflare，平台自带域名和 HTTPS，几分钟就能拿到访问地址，不用管证书。QQ 音乐相关的接入配置，照 docs/qq-music-deployment.md 逐项核对即可。

自部署路线：NAS / 服务器 Docker 全栈

1. 新建一个空目录，放入 deploy/docker/compose.yaml 与环境变量模板
2. 编辑.env，填入SYNC_TOKEN等配置
3. 执行docker compose up -d启动

默认访问地址是http://NAS-IP:18080。完整步骤在 deploy/docker/README.md。

自定义路线：克隆仓库自己管

仓库克隆地址：https://gitcode.com/GitHub_Trending/fo/folia-major。环境变量怎么配，按 docs/technical.md 的说明来，目标平台支持 Node.js 即可。

⚠️ 没有 HTTPS，PWA 就没法可靠安装，也没有离线运行。免费托管平台自带 HTTPS 最省心；NAS 自部署请务必配好反向代理与可信证书，否则手机上很可能根本找不到安装入口。

📲 安卓 / iPhone：各自 4 步上主屏幕

安卓：Chrome 四步添加 Folia 到主屏

1. 用 Chrome 打开 Folia 访问地址
2. 点右上角菜单（⋮）
3. 选「添加到主屏幕」或「安装应用」
4. 确认名称是 Folia，点「添加」

iPhone：Safari 四步添加 Folia 到主屏

1. 用 Safari 打开 Folia 访问地址
2. 点底部分享按钮（⬆️）
3. 上滑找到「添加到主屏幕」
4. 确认名称，点「添加」

装好后主屏出现独立图标。点一下，应用以全屏独立窗口（standalone 模式）启动，没有地址栏和标签页，观感接近原生 App。

为什么一个网页能做到接近原生？拆开看是三处配置：vite.config.ts 的 PWA manifest（应用启动清单）声明了standalone独立窗口、主题色#09090b、512×512 应用图标；index.html 内置apple-mobile-web-app-capable等 iOS 全屏元标签；Service Worker（浏览器里负责拦截请求、缓存文件的小程序）预缓存核心资源并采用autoUpdate自动更新策略——新版部署后，下次打开就是最新版。

🎨 竖屏歌词动画：主题速编与 AI 配色

手机竖着拿，歌词布局会自动响应式重排，动画一条不少。进主题速编入口，随手切风格：

主题配色还能交给 AI：按歌曲情绪与歌词内容自动生成，手机上同样可用。前提是部署时配置了 AI 密钥，不配也不影响正常听歌。

🗄️ 进阶：Navidrome 三步接入，听「自己的歌」

手机端没法直接导入音频文件，Navidrome 补上这一环：

1. 在 NAS 上用 Docker 部署 Navidrome，挂载你的音乐目录
2. 在 Folia 的账户页接入 Navidrome 服务
3. Folia 自动拉取曲库、封面和歌词，歌词动画照常驱动

音频留在 NAS，手机只通过 PWA 远程播放，不占手机存储。本地曲库的管理细节见 docs/local-library-management.md（主要面向桌面端导入流程）。

🔧 卡住了？4 个高频问题一次说清

现象	怎么处理
找不到「添加到主屏幕 / 安装应用」入口	确认地址是 HTTPS；安卓用 Chrome、iOS 用 Safari；重新加载一次，提示有时只在首次访问出现
更新后手机上还是旧版	Service Worker 是autoUpdate策略，下次打开一般自动生效；长时间没更新就清除站点数据，或重新添加到主屏幕
想导入本地音乐文件	手机端不支持，File System Access API 只有桌面端 Chromium 系浏览器有；「自己的歌」走 Navidrome
地铁弱网里打不开	核心界面资源已预缓存，启动没问题；音乐流本身仍要网络

⏱️ 收尾：耗时一览

环节	动作	用时
部署 Folia Web 版	免费平台或 Docker	约 5 分钟
手机打开地址	浏览器输入访问地址	约 10 秒
主屏安装	菜单 / 分享 → 添加到主屏幕	约 1 分钟

不到 10 分钟走完全程。主屏上那个 Folia 图标，点开的就是全屏歌词动画、在线曲库和 Navidrome 歌单的合集——免下载、免安装、随开随听。

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