15 分钟把 Folia 装进手机主屏幕：完整歌词动画播放器部署指南
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia 是一个把全屏歌词动画做进播放器里的 Web 应用，接网易云、QQ 音乐、酷狗、Navidrome 和本地曲库。这篇文章写给想在手机上用它的人：跟着做完，你的主屏幕上就多一个全屏歌词动画播放器，在线搜索、私有曲库、AI 主题配色全都能跑。
Folia 是什么：一个装在手机上的歌词动画播放器
一句话定义：Folia 是以全屏沉浸式歌词播放为核心的音乐播放器，网页打开就是完整形态，再装成 PWA 就拥有独立窗口和离线启动。
核心能力就四条：
- 全屏歌词动画：每种风格带独立排版氛围和可调参数，窗口尺寸变了自动重新分行
- 多源曲库：网易云、QQ 音乐、酷狗、Navidrome 在线拉取，封面与歌词照常驱动动画
- AI 主题配色：按歌曲情绪和歌词生成背景与视觉参数（部署时配了 AI 密钥才可用）
- PWA 独立窗口：vite.config.ts 声明了
standalone显示模式和autoUpdate更新策略
手机场景下能做什么、不能做什么，看这张表就够：
| 能力 | 手机 | 原因 |
|---|---|---|
| 在线搜索与播放（网易云 / QQ / 酷狗） | ✅ | 登录态存在手机浏览器里，换机要重新登录 |
| 全屏歌词动画与主题切换 | ✅ | 排版随竖屏自动重排，动画和光效不受影响 |
| Navidrome 私有曲库 | ✅ | 封面歌词照常驱动，是 NAS 场景首选 |
| 本地音乐文件夹导入 | ❌ | 依赖 File System Access API，只有桌面 Chromium 系浏览器有 |
| 模组系统、壁纸模式 | ❌ | 桌面版专属能力 |
📌 定位一句话：手机上把 Folia 当"歌词动画播放器 + 在线/Navidrome 曲库"用，是最合适的打开方式；导入本地文件夹这类需求留在桌面端。
开始前先确认：4 个前置条件
先别动手部署，这四件事确认完再走后面的路线。
- 地址必须是 HTTPS。这是最硬的门槛：局域网 IP 的普通 HTTP 不属于浏览器安全上下文，Service Worker 装不稳、离线也跑不了。免费托管平台自带 HTTPS；自建部署则要靠反向代理加可信证书把地址变成 HTTPS，配置细节见 deploy/docker/README.md。
- 浏览器用 Chrome 或 Safari。安卓装 PWA 走 Chrome 菜单，iPhone 走 Safari 分享面板，别用第三方浏览器。
- 音乐 API 地址要填。部署时按 docs/technical.md 的环境变量表补齐必填项，至少要有
VITE_NETEASE_API_BASE；变量填错或不填，装好手机后打开就是"能看不能听"。 - 账号在手机浏览器里登录。在线曲库的登录态跟着手机浏览器走，部署完第一次打开时顺手登录即可，换机需要重来一遍。
选一条路线跑起来
三条路线各适合一种人，对号入座：
| 路线 | 适合谁 | 大致耗时 | 一句话特点 |
|---|---|---|---|
| 免费平台一键部署（Vercel / Cloudflare） | 新手 | 5 分钟 | 自带 HTTPS，不用自己管服务器 |
| Docker 全栈部署 | NAS / 自建服务器用户 | 15 分钟 | 音乐 API 随栈打包，和 Navidrome 同机省事 |
| 克隆仓库自行部署 | 想完全自定义 | 30 分钟以上 | 任何支持 Node.js 的平台都能跑 |
路线一：免费平台一键部署
- 在 Vercel 或 Cloudflare 导入 folia-major 仓库并创建项目
- 按 docs/technical.md 的环境变量表补齐必填项，最少填
VITE_NETEASE_API_BASE - 要用 QQ 音乐，按 docs/qq-music-deployment.md 把
VITE_QQ_API_BASE填成/api/qq，并配上QQ_SESSION_SECRET - 等构建完成，拿到带 HTTPS 的地址
路线二：Docker 全栈部署
- 新建一个空目录，放入 deploy/docker/compose.yaml 和环境变量模板
- 执行
openssl rand -hex 32生成随机串，填入SYNC_TOKEN（至少 8 位，不填会拒绝启动） - 执行
docker compose up -d启动 - 浏览器访问
http://NAS-IP:18080，看到曲库页面即成功
⚠️ 局域网 IP 的普通 HTTP 不属于安全上下文，PWA 装不稳也离线不了。用 NAS 自带的反向代理加可信证书把地址改成 HTTPS 再装，代理要传递Host、X-Forwarded-Proto、X-Forwarded-For等头。
路线三：克隆仓库自行部署
- 执行
git clone https://gitcode.com/GitHub_Trending/fo/folia-major - 按 docs/technical.md 准备音乐 API 地址与 AI 密钥等环境变量
- 构建后部署到任意支持 Node.js 的平台
- 手机浏览器打开页面，确认能正常搜索播放
装到手机：安卓 Chrome 与 iPhone Safari 步骤
装的动作本身不复杂，九成失败都栽在 HTTP 上，所以第一步永远是确认地址栏有锁形标志。
安卓：Chrome 添加到主屏幕
- 用 Chrome 打开 Folia 地址，确认地址栏有 HTTPS 锁形标志
- 点右上角菜单（⋮）
- 选"添加到主屏幕"或"安装应用"
- 确认名称显示为 Folia，点"添加"
iPhone：Safari 添加到主屏幕
- 用 Safari 打开 Folia 地址
- 点底部分享按钮
- 上滑找到"添加到主屏幕"并点选
- 确认名称后点"添加"
首次点开会转圈 10 秒左右，那是 Service Worker 在做首次缓存，之后启动快得多。iPhone 上因为页面内置了全屏元标签，点开后没有地址栏，和原生 App 混排在一起。
进阶玩法：主题、AI 配色与 Navidrome 私有曲库
装好只是开始，Folia 的可玩度主要在这两块。
竖着拿手机时歌词按窗口尺寸自动重新分行，动画速度和光效不受影响；部署新版后，Service Worker 走autoUpdate策略，下次打开自动生效。
- 切换主题：主题速编入口里每个风格都带独立的排版氛围和可调参数，OLED 屏幕看深色主题（如 Lumi 流光）对比度最舒服
- AI 配色：支持 Google Gemini 与 OpenAI 兼容接口，根据歌曲情绪和歌词生成背景与视觉参数；部署时没配 AI 密钥就跳过这步
把"自己的歌"放到 Navidrome
手机导入不了本地文件夹，但 NAS 上的歌可以通过 Navidrome 接进来：
- 在 NAS 上用 Docker 跑 Navidrome，挂载音乐目录
- 在 Folia 设置里填 Navidrome 地址、用户名和密码
- 确认后 Folia 拉取曲库、封面与歌词，歌词动画照常驱动
- Docker 全栈用户有省事做法：在
.env里填NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项，backend 会向新打开的浏览器自动下发凭据
⚠️ Folia 走 HTTPS 时，Navidrome 地址也必须是 HTTPS，否则浏览器拦截混合内容，曲库直接连不上。
模组系统同样是进阶方向，但它属于桌面版能力，手机上用不到，这里就不展开了。
出问题时：问答排错与上线前自查
装的时候找不到"添加到主屏幕 / 安装应用"？九成是地址不是 HTTPS。先用锁形标志确认安全上下文，安卓换 Chrome、iOS 换 Safari，再重新加载一次页面。
服务器更新了，手机上还是旧版？Service Worker 是autoUpdate策略，正常情况下次打开自动刷新。长时间没变的话，清除一次站点数据，或删掉图标重新装。
手机能不能直接导入手机里的音乐文件？不能。本地目录导入只有桌面端 Chromium 系浏览器支持（File System Access API 的限制），手机端的"自己的歌"走 Navidrome 方案。
地铁、弱网环境打不开吗？能。核心界面资源已被预缓存，首次加载完成后弱网也能快速启动；音乐流本身仍需网络。
上线前自查清单
逐项核对，全过就可以正式用了：
- 地址栏有锁形标志（HTTPS）吗？
- 用的是 Chrome 或 Safari 吗？
- 部署时网易云等音乐 API 地址填了吗？
- 主屏幕图标名称显示为 Folia 吗？
- 首次打开等了约 10 秒让缓存完成吗？
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
