Folia PWA 安装教程：从部署上线到手机主屏全屏歌词播放

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器 A multi-platform music player for local files, Navidrome, and online streaming services, featuring stunning animated lyrics.项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major

Folia 是一款以全屏歌词动画为核心的音乐播放器，支持网易云、QQ 音乐、酷狗等在线曲库，也支持 Navidrome 和本地音乐。跟完这篇教程，你的手机主屏上会多出一个 Folia PWA 图标，点一下直接进全屏歌词播放，没有地址栏和标签页。整体分四步走：核对 3 个前置条件、在 2 条部署路线里选一条、跑通「登录 → 搜索 → 播放」主流程、再把图标装进主屏，最后接上 Navidrome 就能听自己的歌。

歌词动画有多套主题，排版都会自动适配手机竖屏，不会出现被裁掉的情况。想换风格，在首页的设置入口里切主题即可，快速主题编辑器可以把每个参数逐条微调；部署时如果配了 AI 密钥，主题配色还能按当前歌曲自动生成。

开始前核对 3 个前置条件

PWA 安装失败九成是栽在下面三点上，花两分钟核对一遍，后面基本不卡。

1. 地址必须是 HTTPS。看浏览器地址栏有没有锁形标志。不满足的后果很直接：PWA 安装入口根本不会出现，Service Worker 也无法可靠安装。免费托管平台自动带 HTTPS；NAS 自建的话，给反向代理挂一张浏览器信任的完整证书。
2. 浏览器要对。安卓用 Chrome，iPhone 用 Safari。其他浏览器要么没有「添加到主屏幕」这条路，要么行为不一致，别浪费时间排查。
3. 功能边界划清楚。手机端能做的事：在线搜索播放、全屏歌词动画、Navidrome 曲库。手机上没有的：本地音频文件夹导入——它依赖 File System Access API，只有桌面端的 Chromium 系浏览器支持，手机上不存在这个入口。想听硬盘里的歌，正路是 Navidrome，见第五节。

2 条部署路线，对号入座

拿不准就选路线 A，跑通之后随时可以再迁 Docker。路线 B 的细节（环境变量表、QQ 音乐登录态、反向代理要求）都在 deploy/docker/README.md 里，QQ 音乐在 serverless 和常驻服务之间登录方式的差异另见 docs/qq-music-deployment.md。

部署后 4 步出第一首歌

1. 按选好的路线完成部署。路线 A 等构建结束拿到访问地址；路线 B 按部署文档准备compose.yaml和.env（模板在 deploy/docker/.env.example，至少要填SYNC_TOKEN，AI 相关变量留空不影响播放），执行docker compose up -d --wait。
2. 确认服务活着。路线 B 在浏览器访问http://服务器地址:18080/healthz，返回正常说明网关起来了；路线 A 没有这一步，页面能打开就算通过。
3. 登录音源。打开页面，点顶部的「账户」入口，扫登录二维码，网易云、QQ 音乐、酷狗任选一个。
4. 搜一首歌，点播放。听到声音、看到歌词在动，主流程就跑通了。

登录态存在手机浏览器本地，登一次之后很长一段时间不用再登。

把 Folia 图标装进手机主屏

这一步把网页变成独立应用，两个平台的菜单位置不一样，分开说。

安卓（Chrome）

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

iPhone（Safari）

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

做对了长什么样：点主屏图标，直接弹出独立全屏窗口，界面上找不到地址栏、标签页和浏览器按钮——对，就是装成了。翻不到安装入口的话，回到第一节重新核对 HTTPS 和浏览器。

用 Navidrome 把自己的歌搬上手机

原理很简单：歌始终留在 NAS 上，Navidrome 扫描后对外流式服务，手机 PWA 只负责拉曲库、封面和歌词，音频本身不进手机。

1. 在 NAS 上用 Docker 部署 Navidrome，把音乐目录挂进去。
2. 打开 Folia 设置页，找到 Navidrome 连接设置，填服务器地址、用户名、密码，点测试，通过后保存。
3. 回首页，Navidrome 页签下就是你的歌单和专辑，直接点着播。

验证接对没有，看两点：地址必须是每台设备都够得到的，不能写 Docker 内部主机名；协议要和 Folia 页面匹配，页面走 HTTPS 时它也得是 HTTPS，否则浏览器直接拦截混合内容。个别歌缺歌词的话，智能匹配会自动补在线歌词，动画照常驱动。

Docker 路线还有个省事写法：在.env里填上NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项，新打开的浏览器会带着预置账号自动登录，细节见 deploy/docker/README.md 的「Navidrome 预置账号」一节。本地目录导入的完整规则（支持格式、歌词文件识别、.foliaignore）在 docs/local-library-management.md。

卡住了？对照这张症状表

跑通之后，往这两处进阶

• AI 主题配色：部署时配一个 AI 密钥（Docker 路线在.env里设FOLIA_AI_PROVIDER和对应密钥），主题配色就能按歌曲情绪和歌词内容自动生成，从首页的主题入口触发。各供应商的配置说明见 docs/technical.md。
• 跨设备同步外观：多台设备都要用同一套主题库时，部署 sync-server/，支持 Cloudflare Workers、Docker 和 Node.js 三种托管方式，支持矩阵见 docs/technical.md。

桌面端还有不少手机端没有的玩法：本地目录导入、Folium 模组系统（仓库 mods/ 里有示范模组）、mpv HiFi 播放引擎，想往这边走，从 docs/technical.md 入手。

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器 A multi-platform music player for local files, Navidrome, and online streaming services, featuring stunning animated lyrics.项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major