Folia 部署教程：30 分钟把全屏歌词动画播放器装进手机主屏幕-开发者社区

Folia 部署教程：30 分钟把全屏歌词动画播放器装进手机主屏幕

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

Folia 是一个支持本地音乐、Navidrome 和多平台在线音乐的歌词动画播放器，歌词会以全屏动画推进。这篇指南帮你把 Folia 的 Web 版部署上线，再装成手机主屏幕上的 PWA（Progressive Web App，可安装的网页应用）——点图标直进全屏歌词，不用去应用商店。按一键托管路线 10 分钟出头，Docker 自部署路线大约 30 分钟。

适用判断

适合你：想在没有 App Store 的地方（安卓手机、平板、车载浏览器）随身用 Folia，或者手里有 NAS/服务器、想把歌词动画播放器放进家庭网络的读者。
可以先别读：你的目标是在手机里播放「自己硬盘里没上架任何服务的本地文件」。手机浏览器没有 File System Access API，手机上导入不了本地音乐文件——这条路要先把曲库挂到 Navidrome 上（见文末进阶），或直接使用桌面客户端，本篇不展开。

🚦 30 秒选路线

三个问题，对号入座：

你有自己的服务器或 NAS 吗？有 → 走「Docker 全栈自部署」，仓库 deploy/docker/ 提供完整 Compose 栈，Web、在线音乐接口、Sync Server 一次拉起。
能接受平台托管吗？有 Vercel / Cloudflare 账号、没有服务器 → 走「一键托管」，平台负责构建和 HTTPS，你只填环境变量。
要完全掌控构建产物吗？想改构建配置、自己管 Node.js 版本和变量注入 → 走「手工构建」，clone 后自己 build 再丢到任意静态托管主机上。

默认推荐：没有服务器就选一键托管，PWA 安装和离线运行都依赖 HTTPS 安全上下文（浏览器只信任 HTTPS 下运行的 Service Worker），托管平台免费把这件事做完，新手阻力最小。

📱 落地主线：4 步装到手机上

第 1 步：把 Folia Web 版放到手机能打开的地址

前置：托管路线只需一个 Vercel 或 Cloudflare 账号；自部署路线需要装有 Docker Engine 24+ 与 Compose v2 的机器；手工构建路线需要 Node.js 24+（仓库 package.json 的 engines 字段卡了这条线）。

操作

一键托管：

在仓库 README.md 里找到「一键部署到 Vercel」入口，点按钮创建项目，构建会自动跑npm run build
部署完成后，在项目设置的 Environment Variables 里按 docs/technical.md 的变量表补齐：VITE_NETEASE_API_BASE（网易云 API 实例地址，必需）、VITE_AI_PROVIDER（填google或openai），以及对应的GEMINI_API_KEY/OPENAI_API_KEY，保存后重新部署一次

Docker 自部署：

建一个空目录，从仓库deploy/docker/目录取compose.yaml和.env.example（把后者改名为.env）放进该目录
生成随机串填入SYNC_TOKEN：

openssl rand -hex 32

回显应是一行 64 位的 0-9a-f 字符串；把它复制进.env的SYNC_TOKEN——这一项必填、至少八位，没有默认值。

校验配置并启动：

docker compose config

应完整打印出 YAML，没有「required variable missing」之类的报错。

docker compose up -d --wait

命令会阻塞一段时间（拉镜像 + 健康检查），随后回到提示符。

过线

docker compose ps列表里每行状态都是Up (healthy)，服务包括 gateway、backend、netease-api、kugou-api、qq-api、sync-server
托管路线：手机浏览器打开项目域名，先看到黑底（#09090b）上白色「Folia」字母和一条跳动波形的启动动画，随后出现曲库首页（Playlists / Radio / Albums 标签与搜索框），地址栏有锁标

第 2 步：把地址换成 HTTPS（PWA 安装的前提）

前置：第 1 步已过线，手机能打开你的 Folia 地址。

操作

托管路线：跳过，平台自动签发证书
自部署：在 NAS 或服务器上加一个带可信证书的反向代理，域名指到127.0.0.1:18080，透传X-Forwarded-Proto、X-Forwarded-For等头部，并把.env的FOLIA_HTTP_BIND改成127.0.0.1避免绕过代理。完整清单见 deploy/docker/README.md 的「HTTPS 与浏览器安全上下文」一节

过线

手机打开https://你的域名，地址栏有锁标，点开证书详情没有红色警告，启动动画照常播放

如果停在http://NAS-IP:18080这种裸地址上，属于浏览器安全上下文之外的运行环境：手机上找不到安装入口，离线能力也不生效。反向代理这一层不是可选项。

第 3 步：把图标加到主屏幕

前置：手机浏览器已打开 HTTPS 的 Folia 页面（仓库 index.html 已配好apple-mobile-web-app-capable等元标签，构建产物里带standalone的 manifest，不用你加任何东西）。

操作（只有 Chrome 和 Safari 稳定提供入口，其他浏览器请换过来重开页面）：

安卓 · Chrome：右上角 ⋮ 菜单 →「添加到主屏幕」→ 确认名称显示为 Folia → 添加
iPhone · Safari：底部 ⬆️ 分享按钮 → 上滑找到「添加到主屏幕」→ 确认图标与名称 → 添加

过线：返回桌面，主屏幕上出现 Folia 图标，图标下方名称就是「Folia」——这是安装成功的第一个肉眼证据。

第 4 步：点开图标，验真全屏歌词

前置：图标已上主屏幕。

操作：直接点主屏幕上的 Folia 图标，随便播一首带歌词的歌。

过线

窗口全屏打开，没有地址栏、没有标签栏——这是 manifest 的standalone显示模式生效，普通网页不会这样
状态栏区域与界面黑色主题（#09090b）融为一体，无浏览器 UI 残留
歌词动画随播放推进，旋转屏幕后排版随窗口尺寸重新流动
首次完整加载后断网再开：核心页面直接从缓存打开（Service Worker 预缓存生效），弱网下明显快于普通网页

cappella 群唱主题把歌词排成左右交替的气泡，竖屏窄屏下依旧好读，主题可在设置里切换：

卡点速解

部署前

问：托管部署时没有网易云 API 实例，VITE_NETEASE_API_BASE填什么？答：这项是必需的，先准备一个手机能访问到的网易云音乐 API 实例地址再填；漏填的后果是在线音乐入口可见但点进去没有歌，属于最常见的静默故障。

问：AI 相关变量（VITE_AI_PROVIDER、API Key）必须填吗？答：不是。AI 用于主题生成和歌词分词，留空不影响音乐播放，可以后补。

问：SYNC_TOKEN不填能启动吗？答：不能。它是 Sync Server 的必填项，.env里留空时docker compose config阶段就会报错，不用等到启动才发现。

部署中

问：docker compose up后ps里某项一直 restarting？答：在服务器跑docker compose logs --tail=200 gateway backend netease-api kugou-api qq-api sync-server，按最后 200 行日志定位是哪个服务起不来；健康检查入口分别是 gateway 的/healthz、backend 的/api/healthz和 sync-server 的/health，可手动curl逐一确认。

问：手工构建时 build 失败？答：先确认 Node 版本 ≥24（node -v回显 24.x 才算过线），再看npm run build的具体报错；环境变量只影响运行时行为，一般不会是 build 失败原因。

装完用

问：服务端更新了，手机上还是旧版本？答：Service Worker 是自动更新策略，下次冷启动才换版。完全关闭 PWA 再重新打开；长期不更新就卸载图标、清除站点数据后重新添加。

问：HTTPS 下封面不缓存、选不了音频输出设备？答：多半是证书链不完整、安全上下文被降级。点开证书详情确认链条完整，自签名证书换成可信证书后重启 PWA。

问：装了 Navidrome 预置账号，手机没自动登录？答：先用手机在能打开 Folia 的网络下直接访问NAVIDROME_URL测连通性；Folia 走 HTTPS 时它也要是 HTTPS，否则混合内容被拦截。

🎧 进阶（可选）：接 Navidrome 私有曲库，手机免登录

想让硬盘里的歌出现在 PWA 里，用 Navidrome 做中间层，改动点只有三处：

在 NAS 上用 Docker 部署 Navidrome，挂载你的音乐目录
在 Folia 的.env中填入NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项
执行：

docker compose up -d --force-recreate backend

回显里应看到 backend 容器被重建并重新进入 running 状态；随后手机新打开一次浏览器，会自动登录并启用 Navidrome，全程不用在手机上填账号。

注意事项：NAVIDROME_URL不能写 Docker 内部主机名，必须是各设备都能直接访问到的完整 http(s) 地址；Folia 走 HTTPS 时它也要是 HTTPS。预置凭据默认只下发给局域网来源（NAVIDROME_PRESET_ALLOW=private），公网访问可在.env里收窄或明确放行，细节见 deploy/docker/README.md 的「Navidrome 预置账号」一节。