企业官网建设流程全解析

3 步把 Folia 歌词动画装进手机主屏幕的 PWA 指南

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

地铁里掏手机想听歌、看歌词动画,你多半会打开浏览器,拖标签栏,跟地址栏斗智斗勇。Folia 的 PWA 能力可以把这套流程砍掉:跟着本文操作,几分钟后你的主屏幕上就多了一个 Folia 图标——点开就是全屏窗口,没有地址栏、没有标签页,核心资源预缓存让冷启动更快,服务端一更新手机自动跟上,全程不用 App Store,不用装安装包。

为什么装完体验能这么"像应用"?不是玄学,是构建时写死的: vite.config.ts 里给 PWA manifest 声明了display: 'standalone'独立窗口模式和 512×512 图标, index.html 里带着apple-mobile-web-app-capable这类 iOS 全屏元标签。安卓和 iPhone 拿到的,是同一套全屏体验。

30 秒自检:这篇文章适合你吗

✅ 满足下面三条,往下读;有一条不满足,先去把前提补上。

• 你有一台手机,并且能打开一个 Folia 的 Web 访问地址(自己的、朋友的、或者准备部署一个都行);
• 你要么有一台 7×24 在线的机器(NAS 或服务器),要么愿意用 Vercel / Cloudflare 这类托管平台;
• 最终地址能挂上HTTPS。这是硬性前提,后文还会再讲一遍。

选一条部署路线:2 行对比就够

两条路线的产物是同一个东西:一个可以在手机上装 PWA 的 HTTPS 地址。选哪条只取决于你有没有机器,不用纠结。

⚠️HTTPS 是装 PWA 的入场券。Service Worker 的注册、"添加到主屏幕"的触发、离线缓存,都只在 HTTPS 安全上下文里稳定工作。免费托管平台自带证书,不用管;NAS 自部署必须让反向代理终止 HTTPS 并装上浏览器信任的完整证书链——自签名证书不算数。证书不对,"安装应用"选项可能压根不出现。

Docker 私有化部署方法:NAS 上起完整曲库栈

⚠️ 前提:Docker Engine 24+ 和 Docker Compose v2。下面的地址NAS-IP换成你机器的实际 IP。

1. 建目录,拉两个文件。新建空目录,把 deploy/docker/compose.yaml 和环境变量模板 deploy/docker/.env.example 放进同一目录,后者改名为.env。(可验证现象:目录里刚好两个文件,compose.yaml和.env。)
2. 生成并填入 SYNC_TOKEN。执行openssl rand -hex 32,把输出粘进.env的SYNC_TOKEN,同时确认FOLIA_IMAGE_NAMESPACE有值。AI 密钥可以留空,不影响播放。(可验证现象:.env里至少这两项不再是空值或占位符。)
3. 启动并等健康检查通过。依次执行docker compose pull和docker compose up -d --wait。(可验证现象:docker compose ps里所有容器都是 healthy 状态。)
4. 浏览器访问http://NAS-IP:18080。能打开 Folia 首页,搜索、播放都正常,说明后端栈已经就绪。(可验证现象:页面顶部有 Playlists / Radio / Albums 等页签,搜索框可输入。)

局域网 IP + 普通 HTTP 这个状态,在线曲库和歌词动画都能用,但装不了 PWA。下一步补 HTTPS。

给 Folia 挂上 HTTPS 反代

1. 在反代上建一个站点(Caddy、Nginx 或 NAS 自带的 HTTPS 面板都行),域名指向http://127.0.0.1:18080。
2. 确认四个头都透传:Host、X-Forwarded-Host、X-Forwarded-Proto: https、X-Forwarded-For;有代理的情况下,把代理自己的 IP 填进.env的FOLIA_TRUSTED_PROXIES,然后执行docker compose up -d --force-recreate gateway。(可验证现象:浏览器地址栏出现锁形标志,https://开头。)
3. 建议把FOLIA_HTTP_BIND改成127.0.0.1,避免流量绕过代理。(可验证现象:直接访问NAS-IP:18080不再通,只有域名可访问——这正是你要的效果。)

完整的反代配置、回滚和备份流程,见 deploy/docker/README.md。

安卓安装步骤:Chrome 里的 3 个动作

安卓侧只有 Chrome 给全套安装入口,其他浏览器可能不显示,换浏览器别怪教程:

1. 用 Chrome 打开你的 Folia HTTPS 地址。(可验证现象:页面正常加载,地址栏带锁。没有锁说明 HTTPS 没配好,先回上一节。)
2. 点右上角菜单(⋮),选"添加到主屏幕"或"安装应用"。(可验证现象:弹出确认对话框,应用名显示为 Folia。)
3. 确认名称,点添加。(可验证现象:主屏幕上出现 Folia 图标,点开是全屏窗口——没有地址栏、没有标签页,直接进播放界面。)

装好后建议再刷一次页面,让 Service Worker 完成首次预缓存;之后即使弱网,启动本身也不挑网络了。

iPhone 安装步骤:Safari 里的 4 个动作

iOS 的入口藏得跟安卓不一样,必须走 Safari:

1. 用 Safari 打开 Folia HTTPS 地址。(可验证现象:地址栏显示你的域名,页面正常加载。)
2. 点底部那个"分享"按钮(方框带向上箭头)。(可验证现象:屏幕上方滑出一列操作菜单。)
3. 在菜单里往下滑,点"添加到主屏幕"。(可验证现象:进入一个应用预览页,能看到 Folia 的图标和名称。)
4. 点右上角"添加"。(可验证现象:图标落到主屏幕,点开是独立全屏窗口,顶部状态栏样式跟随应用的black-translucent配置。)

一个小细节:系统有时只在首次访问时弹一次安装提示,错过了就自己走上面四步;四步走完还没看到入口,先确认是不是 Safari、地址是不是 HTTPS,然后刷新再试。

装完看到什么:竖屏歌词动画与 AI 配色

竖屏自动重排的全屏歌词动画

Folia 的招牌是一整套全屏歌词动画主题,每个主题有自己的排版氛围和一批可调参数。手机竖屏下,版式会跟着窗口尺寸自动重排——歌词重新组织,动画照样流畅,不会挤成一团。下面是 Folia 全屏歌词动画主题的实际效果:

想换风格不用翻设置,走"主题速编"入口就能调。

按歌曲情绪推导的 AI 主题配色

主题的色板可以由 AI 根据歌曲情绪和歌词内容自动推导,手机端同样可用。前提是部署时配了 AI 密钥(托管平台填在环境变量里,Docker 填在.env的GEMINI_API_KEY/OPENAI_API_KEY等字段),相关实现集中在 shared/ai/ 目录。没配也不影响播放,只是少了这个彩蛋。

用 Navidrome 私有曲库听"自己的歌"

手机浏览器没有 File System Access API,本地目录导入这个入口在设计上就不存在。想听自己盘里的歌,走 Navidrome:NAS 上 Docker 起一个 Navidrome 挂载音乐目录,再在 Folia 的账户页填入服务地址;Docker 部署的话直接在.env填NAVIDROME_URL/NAVIDROME_USERNAME/NAVIDROME_PASSWORD三项,新打开的浏览器会自动接上。Folia 会把曲库、封面、歌词一次拉齐,缺失的歌词还能走智能匹配自动补上。歌安静地待在 NAS 上,手机远程连同一个曲库,不吃手机存储:

曲库管理的具体细节可以看 docs/local-library-management.md。

避坑清单

1. 找不到"添加到主屏幕 / 安装应用"入口——九成是地址没上 HTTPS 或浏览器没对齐:安卓用 Chrome、iPhone 用 Safari,确认https后刷新一次。
2. 服务端更新了,手机还停在旧版——Service Worker 走autoUpdate,下次打开一般会切;长时间不动就清一次站点数据,或从主屏幕移除后重新添加。
3. 想在手机上导入本地音乐文件——做不了,这是桌面端 Chromium 系浏览器的独占能力;官方绕法就是 Navidrome 私有曲库,见上节。
4. 地铁弱网里播放卡顿——首屏启动靠预缓存不挑网络,但音乐流还是走网络,弱网卡顿属于预期表现,不是故障。
5. Folia 走了 HTTPS 后 Navidrome 连不上——浏览器会拦截混合内容,Navidrome 的地址同样要上 HTTPS,否则前端连不上。
6. 换 HTTPS 之后发现登录态和设置"丢了"——HTTP 与 HTTPS 是两个不同的 origin,数据不会自动迁移,属正常现象。
7. 反代配了但来源判断异常——检查X-Forwarded-For是否透传、FOLIA_TRUSTED_PROXIES是否只填了代理的确切地址,细节在 deploy/docker/README.md 里有专门一节。

想更深入地看环境变量和架构,翻 docs/technical.md;QQ 音乐的环境变量写法照着 docs/qq-music-deployment.md 抄就行。

从网页到主屏幕图标:拿到地址、手机打开、点进菜单、确认名称、点一下——5 下操作,现在就掏出手机试试。

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