Folia 歌词动画播放器部署指南：把 PWA 装进手机主屏幕，全程 4 条命令 5 分钟

Folia 歌词动画播放器部署指南把 PWA 装进手机主屏幕全程 4 条命令 5 分钟【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-majorFolia 是一款主打歌词动画的播放器支持本地音乐、Navidrome 与第三方平台在线音乐。本文带你完成 Folia 歌词动画播放器 PWA 部署把 Web 版放到手机够得到的 HTTPS 地址再从主屏幕全屏启动。全程约 5 分钟核心动作 4 条命令每步都附预期效果随时自查有没有做对。路线决策三条部署路线怎么挑路线适合谁前置条件含检查项最大坑一键托管Vercel / Cloudflare没有服务器、想最快出结果的人一个托管平台账号部署后用 HTTPS 地址在手机浏览器打开一次确认能看到启动动画环境变量漏配在线音乐入口可见点进去没有歌容器自部署Docker 全栈有 NAS 或自建服务器的人Docker Engine 24 与 Compose v2一台能挂 HTTPS 反向代理的域名默认入口是裸 HTTP不属于浏览器安全上下文PWA 安装入口直接消失手工构建clone 后自行构建想自定义构建产物与变量的人Node.js 24node -v确认自带 HTTPS 的托管主机步骤最多HTTPS、环境变量、构建都要自己管默认走一键托管PWA 安装与离线缓存都依赖 HTTPS 安全上下文托管平台免费把这件事做完你只剩填变量一个动作。执行主线部署 Folia 并装到主屏幕主线分三个阶段编号连续。一键托管路线走 1–4Docker 路线从 5 走到 10两条路线都从第 11 步继续。部署 Web 版1. 一键托管路线按 docs/technical.md 的「一键部署到 Vercel」入口创建项目等构建结束。预期效果项目列表里该项目状态变为 Ready拿到一个形如xxx.vercel.app的 HTTPS 域名。2. 补齐环境变量进入项目设置的 Environment Variables按该文档的变量表至少填VITE_NETEASE_API_BASE在线音乐 API 实例地址与VITE_AI_PROVIDERgoogle或openaiAI 主题、歌词分词依赖它QQ 音乐可选填VITE_QQ_API_BASE/api/qq走仓库内置的 serverless 入口。保存后重新部署一次。预期效果重新部署完成环境变量在设置里显示为已设置而非空值。3. 手机浏览器打开项目域名。预期效果地址栏出现锁形标识页面先播放黑底 Folia 启动动画随后出现曲库首页Playlists / Radio / Albums 标签与搜索框。4.仅 Docker 路线取部署文件clone 仓库把deploy/docker/下的compose.yaml与.env.example复制进一个空目录。git clone --depth 1 https://gitcode.com/GitHub_Trending/fo/folia-major预期效果当前目录出现folia-major文件夹folia-major/deploy/docker/里能看到compose.yaml。5. 生成同步令牌openssl rand -hex 32预期效果输出一行 64 位的0-9a-f字符串这是SYNC_TOKEN的取值。6. 填入 .env把.env.example改名为.env粘贴一行SYNC_TOKEN第 5 步的输出。SYNC_TOKEN必填至少八位没有默认值缺了它 Sync Server 拒绝启动。AI 相关配置可留空不影响音乐播放。预期效果.env中存在SYNC_TOKEN且值不为空。7. 拉镜像并启动整套服务docker compose pull docker compose up -d --wait预期效果--wait让命令阻塞到全部服务通过健康检查后自动返回提示符不报 unhealthy。8. 核对服务状态docker compose ps预期效果列表每行显示Up (healthy)。9. 验证网关入口curl http://127.0.0.1:18080/healthz预期效果返回健康检查内容而非连接拒绝。10. 挂反向代理在 NAS 或服务器上配置带可信证书的代理把https://你的域名指到http://127.0.0.1:18080Sync Server 为http://127.0.0.1:13000透传Host、X-Forwarded-Host、X-Forwarded-Proto、X-Forwarded-For四个头部并把 HTTP 请求重定向到 HTTPS。完整清单见 deploy/docker/README.md 的「HTTPS 与浏览器安全上下文」一节。代理跑在宿主机时可把.env的FOLIA_HTTP_BIND、FOLIA_SYNC_BIND改成127.0.0.1防止绕过代理。预期效果手机浏览器打开https://你的域名证书无红色警告看到第 3 步描述的启动动画与首页。默认入口http://NAS-IP:18080是普通 HTTP不属于浏览器安全上下文手机上找不到安装入口。反向代理这一层不是可选项。安装到主屏幕11. 按设备型号执行安装两种入口并排放好步骤安卓 · ChromeiPhone · Safari1点右上角 ⋮ 菜单点底部 ⬆️ 分享按钮2选「添加到主屏幕」上滑找到「添加到主屏幕」3确认名称显示为 Folia 或 Folia Music点「添加」确认名称与图标点「添加」只有 Chrome安卓和 SafariiPhone能稳定给出「添加到主屏幕」入口其他浏览器换过来重新加载页面再做这一步。index.html 与 vite.config.ts 已配好apple-mobile-web-app-capable等元标签和standalonemanifest你不需要加任何东西。12. 验证安装成功返回桌面。预期效果主屏幕出现 Folia 图标名称即第一个安装证据。启动并验真13. 点主屏幕图标。预期效果窗口全屏打开没有地址栏、没有标签栏——manifest 的standalone显示模式生效普通网页不会这样状态栏区域与界面底色#09090b融为一体没有浏览器 UI 残留。14. 播一首带歌词的歌。预期效果歌词动画开始推进旋转屏幕后排版随窗口尺寸重新流动无错位。分档验收当场、断网、长期当场能验的点图标全屏启动地址栏与标签栏均不存在状态栏与#09090b界面融为一体看不到浏览器痕迹带歌词歌曲播放时歌词逐行推进旋转屏幕排版自动重排断网后验的首次完整加载后断开 Wi-Fi 并切飞行模式关闭 PWA 再重新打开核心页面直接从缓存打开弱网下明显快于普通网页Service Worker 预缓存生效恢复网络后完全关闭 PWA 再冷启动地址不变的情况下仍进入新版本autoUpdate策略在下次冷启动换版用一段时间才能验的服务端更新后PWA 最迟在下一次冷启动进入新版不需要卸载重装切换主题后窄屏歌词自动重排字距行距不溢出屏幕连续使用数日播放、封面、歌词缓存不出现明显膨胀或失效高频问题自检现象对照表按出现概率从上往下查现象最可能原因处理动作找不到「添加到主屏幕」地址是 HTTP或浏览器不是 Chrome / Safari换 HTTPS 地址换 Chrome安卓或 SafariiPhone重新加载页面再找一次在线搜索、播放没有反应环境变量没填或填错在托管平台项目设置按 docs/technical.md 的变量表补VITE_NETEASE_API_BASE等项保存后重新部署服务端更新了手机还是旧版本Service Worker 为autoUpdate策略下次冷启动才换版完全关闭 PWA 再重新打开长期不更新就卸载图标、清除站点数据后重新添加HTTPS 下封面不缓存、选不了音频输出设备证书链不完整安全上下文被降级点开证书详情确认链条完整自签名证书换成可信证书重启 PWA配了 Navidrome 预置账号手机没自动登录NAVIDROME_URL手机访问不到或混合内容被拦截用手机在同一网络下直接打开NAVIDROME_URL测连通性再到 Folia 设置里手动打开 Navidrome 开关docker compose up -d --wait卡住或失败SYNC_TOKEN没填或不足八位回到第 5、6 步重新生成并填入再docker compose up -d --wait手机浏览器没有 File System Access API手机上不能导入本地音乐文件——那个功能只存在于桌面版。想听硬盘里的歌走 Navidrome 路线见下文第 7 节。可选扩展Navidrome 私有曲库手机免登录动机默认情况下 Navidrome 账号保存在各浏览器自己的 localStorage 里手机、电视、电脑要各登录一次。把凭据交给服务器下发后新浏览器打开 Folia 就自动登录并启用全程不用在手机上填账号。1. 在 NAS 上用 Docker 部署 Navidrome挂载你的音乐目录。预期效果浏览器打开 Navidrome 地址能看到你的曲库。2. 在 Folia 的.env中填入三项重建 backendNAVIDROME_URLhttp://NAS-IP:4533 NAVIDROME_USERNAMEfolia NAVIDROME_PASSWORD... docker compose up -d --force-recreate backend预期效果backend 容器重建完成并回到 healthy。3. 手机新打开一次浏览器访问 Folia。预期效果自动登录并启用 Navidrome首页直接出现你的曲库没有任何输入动作。NAVIDROME_URL必须写各设备都能访问到的地址不能写 Docker 内部主机名Folia 走 HTTPS 时它也要是 HTTPS否则浏览器拦截混合内容。预置凭据默认只交给局域网来源NAVIDROME_PRESET_ALLOW控制放行范围细节见 deploy/docker/README.md 的「Navidrome 预置账号」一节。部署一次、装一次主屏幕多一台全屏歌词动画播放器三种曲库都收在这一个图标里。部署细节回看 deploy/docker/README.md 与 docs/technical.md。【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考