免费快速完整指南：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 全栈
- 新建一个空目录，放入 deploy/docker/compose.yaml 与环境变量模板
- 编辑
.env，填入SYNC_TOKEN等配置 - 执行
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 到主屏
- 用 Chrome 打开 Folia 访问地址
- 点右上角菜单（⋮）
- 选「添加到主屏幕」或「安装应用」
- 确认名称是 Folia，点「添加」
iPhone：Safari 四步添加 Folia 到主屏
- 用 Safari 打开 Folia 访问地址
- 点底部分享按钮（⬆️）
- 上滑找到「添加到主屏幕」
- 确认名称，点「添加」
装好后主屏出现独立图标。点一下，应用以全屏独立窗口（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 补上这一环：
- 在 NAS 上用 Docker 部署 Navidrome，挂载你的音乐目录
- 在 Folia 的账户页接入 Navidrome 服务
- 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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
