Folia 手机端使用指南：如何部署 Web 版并把全屏歌词动画播放器装进手机主屏

Folia 手机端使用指南：如何部署 Web 版并把全屏歌词动画播放器装进手机主屏

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

Folia 是一款主打全屏歌词动画的音乐播放器，支持网易云、QQ 音乐、酷狗与 Navidrome 曲库。这篇指南带你走完「部署 Folia Web 版 → PWA 安装到手机主屏 → 接入在线或自建曲库」三步，全程不用写代码。

装进手机后能干什么：三个真实使用场景

• 车里：导航和播放都在手机上完成，全屏歌词动画开着就是一座随身屏幕，通勤时间有了去处。
• 睡前：手机搁在枕头前，竖屏下歌词动画完整可用，各主题排版都会自适应窄屏，不裁剪也不拥挤。
• 客厅、出差：接上自建曲库后，歌文件留在 NAS 里，手机只负责拉曲库、封面和歌词，边听边看词。

装好之后的最终画面：点主屏图标，Folia 以独立全屏窗口启动，没有地址栏和标签页，观感接近原生应用；登录态、主题偏好都保存在手机浏览器里，一次配置长期有效。

时间预期：走一键托管 + 在线曲库的主路径，全程约 30 分钟，其中动手操作不超过 5 分钟，其余都在等部署跑完。

动手前花 5 分钟：部署前置自查清单

• 选定部署路线：一键云托管、NAS Docker、完全自建三选一，各自适合谁见下一节
• 手机浏览器对号入座：安卓用 Chrome，iPhone 用 Safari，其他浏览器可能没有安装入口
• 访问地址是 HTTPS：PWA 安装依赖浏览器安全上下文，纯 HTTP 会缺失安装入口；免费托管平台自带 HTTPS，NAS 自托管则需配一层反向代理（把外部请求转发到本地服务的中间层）加可信证书
• 曲库账号就绪：网易云、QQ 音乐、酷狗登录态随手可扫；走 Navidrome 路线则需一台放着音乐的 NAS
• 预期对齐：在线搜索播放、歌词动画、Navidrome 曲库都能用；导入手机本地的音频文件不可用

三条部署路线：把 Folia Web 版放到手机够得到的地址

零基础路线：一键云托管

适合没有服务器、第一次折腾的人。

1. 打开项目 README.md，点内置的 Vercel 或 Cloudflare 一键部署按钮。
2. 授权后等几分钟，得到一个带 HTTPS 的地址，域名和证书都不用管。
3. 要用 QQ 音乐的话，在环境变量里把VITE_QQ_API_BASE填成/api/qq，再加一个服务端密钥，完整步骤见 QQ 音乐部署指南。

环境变量一行说明：VITE_QQ_API_BASE指向平台内置的 serverless（按需运行、无需常驻服务器）API 入口，服务端密钥不加VITE_前缀。

验证：用手机浏览器打开新地址，Folia 启动画面出现、地址栏有锁标志，这一步就算成功。

NAS 路线：Docker 容器栈部署

适合已有 NAS 或服务器、习惯把音乐存网盘的人。

1. 从仓库取 deploy/docker/compose.yaml 和.env.example环境变量模板，放进同一目录并改名为.env。
2. 编辑.env，把SYNC_TOKEN填成一个至少 8 位的随机字符串（同步客户端的访问令牌）。
3. 执行docker compose up -d在后台启动整套服务。

Web 入口默认是http://NAS-IP:18080（把NAS-IP换成你的机器地址）；端口、环境变量、反向代理与证书的细节都在 deploy/docker/README.md 里。

验证：先在电脑上打开地址，页面正常且/healthz有响应；再确认手机也能打开同一地址，打不开就说明网络不通，先解决网络再谈安装。

掌控路线：克隆仓库自行部署

适合想把环境变量、构建、HTTPS 全握在自己手里的人。

执行git clone https://gitcode.com/GitHub_Trending/fo/folia-major，克隆下来后按 docs/technical.md 自行配置部署即可。

验证：与上面相同，用手机浏览器打开最终地址确认页面正常。

把 Folia 装进手机主屏：安卓与 iPhone 安装步骤

安卓手机 Chrome 安装步骤

1. 用 Chrome 打开 Folia 的 HTTPS 地址。
2. 点右上角菜单（⋮）。
3. 选「安装应用」或「添加到主屏幕」。
4. 确认名称为 Folia，点添加。

这一步做完你可以检查：点主屏图标，Folia 以独立全屏启动、没有地址栏，就是装对了；如果还是开成浏览器页面，说明地址是 HTTP 或浏览器不对，换回指定条件重试。

iPhone Safari 安装步骤

1. 用 Safari 打开 Folia 的 HTTPS 地址。
2. 点屏幕底部的分享按钮。
3. 上滑找到「添加到主屏幕」，点击。
4. 确认名称，点添加。

验证方式相同：启动即全屏独立模式，看不到任何浏览器痕迹。

装好后，在账户页登录网易云、QQ 音乐或酷狗。登录态存在手机浏览器里，登录一次之后很长一段时间不用重复登。

接入自己的歌：三步接 Navidrome 自建曲库

原理一句话：歌放在 NAS 上，Navidrome（开源自建音乐流媒体服务）扫描后以流媒体曲库对外服务，手机 PWA 只负责拉曲库、封面和歌词，文件不进手机，省空间也省流量。

1. 在 NAS 上用 Docker 部署 Navidrome，挂载你的音乐目录。
2. 在 Folia 的账户页接入 Navidrome：地址必须是每台设备都够得到的地址，不能写 Docker 内部主机名；Folia 页面走 HTTPS 时它也得是 HTTPS，否则浏览器会拦截混合内容。
3. 曲库与封面同步完成后直接播放，缺失的歌词由智能匹配自动补齐，歌词动画照常驱动。

Docker 全栈用户可以把NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项填进.env，新打开的浏览器会被自动下发预置账号，不用每台设备各登一次。

桌面端本地曲库的管理方式可参考 docs/local-library-management.md。

常见问题：出问题时集中排一次

• 菜单里找不到「添加到主屏幕」：多半是 HTTP 地址或浏览器不是 Chrome/Safari。换成 HTTPS 地址和指定浏览器，再重载一次页面。
• 线上已更新，手机打开还是旧界面：Service Worker（浏览器本地缓存程序）的更新时机通常滞后一次打开。清除该站点的浏览器数据，或删掉图标重新添加。
• 手机端为什么没有本地导入入口：本地目录导入依赖 File System Access API（让网页直接读取本地文件夹的浏览器接口），只有桌面端 Chromium 系浏览器支持，手机端本来就没有这个入口。想听「自己的歌」走 Navidrome 路线。
• Navidrome 连上了，曲库封面却拉不下来：多半填了 Docker 内部主机名，手机够不到；或页面是 HTTPS 而 Navidrome 地址是 HTTP。改成各设备可达的地址，需要时对齐到 HTTPS。
• HTTP 换成 HTTPS 后，登录态和设置都没了：两个地址属于不同 origin（浏览器按协议 + 域名 + 端口区分的身份），数据不会自动迁移。重新登录配置一遍即可，地址定型后别再来回切换。

能力边界与建议上手顺序

手机端能做什么、不能做什么

能做的：

• 在线搜索播放：网易云、QQ 音乐、酷狗，扫码登录一次长期有效
• 全屏歌词动画：竖屏完整可用，主题排版响应式适配窄屏
• Navidrome 自建曲库：文件留在 NAS，手机流式播放
• 装进主屏独立启动：无地址栏，接近原生应用体验
• AI 按歌生成主题配色（部署时配了对应 AI 密钥才可用）

不能做的：

• 导入手机本地的音频文件：入口在手机上不存在，本地目录导入只属于桌面端
• 桌面版的模组系统、视频导出等完整能力：这些留在桌面版

不同主题有不同的排版氛围和可调参数，手机上换风格走「主题速编」入口即可。

建议上手顺序

1. 先用一键托管把 Web 版跑起来，接一个在线曲库，把「搜索 → 播放 → 歌词动画」的完整流程走通。
2. 稳定之后接 Navidrome，把「自己的歌」补进来。
3. 需要跨设备同步主题与设置时，再升级到 Docker 全栈（内置 Sync Server）。

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