Folia 手机端完整指南：3 条部署路线，把手机变成全屏歌词动画播放器

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

想用手机跑 Folia？这篇把整条链路一次讲清：先把 Web 版放到一个手机够得着的 HTTPS 地址上，再以 PWA 形式装进主屏幕，之后每次一点图标，进来的就是一台全屏歌词动画播放器。在线曲库走网易云、QQ 音乐、酷狗，NAS 上的私有曲库走 Navidrome，都能跑；唯一的短板是本地文件夹导入——那本来就是桌面端的能力。

先看能力清单：手机上能干什么、不能干什么

一句话定位：在手机上，Folia 就是全屏歌词动画播放器，内容来源是线上曲库或 Navidrome。

能做的：

• ✅ 在线搜索和点歌（网易云 / QQ 音乐 / 酷狗）。账号绑定在手机浏览器里，换机器得重新登录
• ✅ 全屏歌词动画。竖着拿手机时，歌词排版自动重排，动画节奏和光效不缩水
• ✅ Navidrome 私有曲库。曲库在 NAS 上的话这是首选，封面歌词照样驱动动画
• ✅ AI 自动生成主题配色。部署时配过 AI 密钥才亮，没配就跳过这项

不能做的：

• ❌ 导入本地音乐文件夹。底层用的 File System Access API 只存在于桌面端的 Chromium 系浏览器，手机上没有
• ❌ 模组系统与壁纸模式。这两样只在桌面版开放

📌 所谓"安装 Folia"，本质是收藏一个能全屏、能部分离线的网页。前提是 Web 版得先上线，且地址必须是手机可访问的 HTTPS。

上线部署：三条路线，同一件事

三条路线只服务一个目标——拿到 HTTPS 地址。按你手上有没有服务器来挑。

没有服务器：托管平台一键部署，约 5 分钟

新手走这条，Vercel 或 Cloudflare 自带 HTTPS，不用碰运维。

1. 在 Vercel 或 Cloudflare 导入 Folia 仓库，创建项目
2. 打开 docs/technical.md，对照环境变量表补必填项，最少要填VITE_NETEASE_API_BASE
3. 想用 QQ 音乐，照 docs/qq-music-deployment.md 把VITE_QQ_API_BASE填成/api/qq，再配上QQ_SESSION_SECRET
4. 等部署结束，记下带 HTTPS 的地址

有 NAS 或自建机：Docker 全栈，约 15 分钟

在线音乐接口整个打进镜像里，跟 Navidrome 放同一台机器最省心。

1. 新建目录，放入 deploy/docker/compose.yaml 与环境变量模板，模板说明在 deploy/docker/README.md
2. 跑openssl rand -hex 32拿一串随机字符，粘进SYNC_TOKEN
3. docker compose up -d启动
4. 浏览器打开http://NAS-IP:18080，见到曲库页面就算成功

⚠️ 局域网 IP 配普通 HTTP，浏览器不算安全上下文，PWA 装不稳，也离线不了。请用 NAS 自带的反向代理挂可信证书，把地址换成 HTTPS 再装，反代细节看 deploy/docker/README.md。

想完全自定义：克隆仓库自建，30 分钟起

任何支持 Node.js 的平台都能落。

1. git clone https://gitcode.com/GitHub_Trending/fo/folia-major
2. 打开 docs/technical.md 的环境变量说明，备好音乐 API 地址与密钥
3. 构建完成之后，丢到任意支持 Node.js 的平台
4. 手机浏览器打开地址，搜索、播放都能用才算过

装机：两款系统各四个点击

安卓 Chrome：添加到主屏幕的完整路径

先自查：地址栏有没有 HTTPS 的锁形标志。没有锁的话，"添加到主屏幕"选项九成不出现，这是装不上时最常见的原因；安卓换 Chrome、iOS 换 Safari，再刷新一次页面。

1. 用 Chrome 打开 Folia 地址
2. 点右上角 ⋮ 菜单
3. 选"添加到主屏幕"或"安装应用"
4. 名字是 Folia 就点"添加"

iPhone Safari：主屏幕上加上 Folia 图标

1. 用 Safari 打开 Folia 地址
2. 点屏幕底部的分享图标
3. 上滑列表，找到"添加到主屏幕"
4. 核对名称，点"添加"

首次打开大约会转 10 秒——这段时间 Service Worker 在本地缓存资源，之后的启动会快一大截。另外页面里内置了全屏元标签，iPhone 上点开之后看不到地址栏，跟原生 App 混排毫无违和感。

进阶：用 Navidrome 把"自己的歌"搬上 NAS

手机想播自己的音乐，只有 Navidrome 这一条正路。

1. NAS 上用 Docker 跑 Navidrome，把音乐目录挂载进去
2. 在 Folia 设置页填 Navidrome 地址、用户名和密码
3. 确认之后，曲库、封面、歌词都会被拉下来，歌词动画照常驱动
4. Docker 全栈用户有省事写法：.env里写全NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项，backend 会在浏览器新打开时把凭据推过去，省去手动输入

⚠️ Folia 走 HTTPS 时，Navidrome 地址也必须 HTTPS，否则浏览器会拒绝混合内容，曲库直接连不上。

装好之后：更新、主题与弱网表现

vite.config.ts 里声明了 PWA 的独立窗口显示与autoUpdate自动更新策略——部署新版本后，下次打开就自动生效。要是卡在旧版不走，清一次该站点数据，或把图标删了重新装。

日常可调的几项：

• 切主题：主题速编里每种风格各有排版氛围，参数都能细调
• AI 配色：兼容 Google Gemini 与 OpenAI 接口，读懂歌曲情绪和歌词后自动给出背景与视觉参数
• OLED 屏：深色主题（比如 Lumi 流光）对比度最舒服
• 弱网：核心界面资源已预缓存，首次加载完整后，地铁里也能快速启动；音乐流本身仍要联网

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