企业官网建设流程全解析

完整指南：4 步部署 Folia 全屏歌词播放器并装进手机主屏

【免费下载链接】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 远端曲库。本文分 4 步走通：部署 Web 版、验证搜索播放、把 PWA 装进主屏、用 Navidrome 接自己的曲库，全程 15-30 分钟。做完之后，点一下主屏图标，歌词动画就铺满整块屏幕。

部署之后：歌词铺满整块竖屏

效果一句话：装进手机后歌词居中撑满竖屏，底部只留一条迷你播放条，每个主题的排版都会自动适配竖屏。

总耗时 15-30 分钟（取决于走哪条路线）。适合想在手机上听在线音乐或自己 Navidrome 曲库的人；如果你的诉求是把手机里的本地音乐文件夹导进播放器，这条路走不通，Web 端没有这个入口。

🔍 动手前自查：三个问题先确认

多数人的问题都出在准备阶段，下面三项核一遍，后面基本不会再卡：

1. 地址栏有没有锁形标志？没有就是 HTTPS 没配好，PWA 安装入口根本不会出现。路线 A 天然带 HTTPS；路线 B 需要在 NAS 反向代理上挂可信证书。
2. 浏览器是 Chrome（安卓）还是 Safari（iPhone）？其他浏览器要么没有「添加到主屏幕」入口，要么行为不一致。
3. 页面能打开、搜索有结果吗？搜索框能出结果，说明服务是活的；出不了就先回到部署小节排查。

能力边界也划清楚：

路线 A：Vercel 一键部署（免服务器）

1. 打开 Folia 仓库首页，点顶部的 "Deploy with Vercel" 按钮创建项目，一步到位（Cloudflare 同理；想省事就选 Vercel，门槛最低）。
2. 构建结束后直接拿到 https 地址，域名和证书都不用管。
3. 手机打开页面，点顶部「账户」，登录网易云、QQ 音乐或酷狗任意一个。
4. 搜一首歌，点播放，进入全屏歌词。

判断做对没有：页面打开、搜索有结果、声音出来、歌词在动，最小链路就算跑通。登录后账号状态存在浏览器本地，同一地址下很长一段时间不用反复登录。

注意：在 Vercel 登录 QQ 音乐要填环境变量VITE_QQ_API_BASE=/api/qq，并另配服务端密钥QQ_SESSION_SECRET（不带VITE_前缀），细节见 docs/qq-music-deployment.md。

拿不准就先跑通路线 A，后面想切路线 B 随时能切，地址换掉之后重新登录、补一遍配置即可。

路线 B：NAS / 自建 Docker 全栈部署

1. 在 NAS 上建一个空目录，放入compose.yaml和.env两个文件（.env由同目录.env.example生成）。
2. .env至少填两项：FOLIA_IMAGE_NAMESPACE（默认papersman）和SYNC_TOKEN（可用openssl rand -hex 32生成）；AI 密钥可留空，不影响播放。
3. 启动：docker compose pull && docker compose up -d --wait
4. 验证：curl http://NAS-IP:18080/healthz，返回正常说明网关起来了；再照路线 A 的第 3、4 步登录、搜索、播放。

局域网 IP 加 HTTP 只能搜索和播放，PWA 安装不可靠；要装进手机，让 NAS 反向代理终止一张可信的 HTTPS 证书。环境变量、QQ 登录态、反向代理细节都在 deploy/docker/README.md。

不想养服务器时，随时可以再整体迁回托管路线，配置就是环境变量一组，迁移不折腾。

📱 把 Folia 添加到手机主屏幕

安卓：Chrome 添加到主屏幕

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

iPhone：Safari 添加到主屏幕

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

判断装对了没有：点图标直接进入全屏模式，画面里看不到地址栏和标签页，就算装成了。

接 Navidrome：把自己的曲库流式送上手机

原理很简单：音频文件一直留在 NAS 上，Navidrome 扫描后提供流式播放，Folia 页面只拉列表、封面和歌词。

1. 在 NAS 上用 Docker 部署 Navidrome，把音乐目录挂进容器。
2. 打开 Folia 设置页，找到 Navidrome 连接一栏，填服务器地址、用户名、密码，点「测试连接」。
3. 测试通过后保存，回首页 Navidrome 页签直接点歌播放。

接对没有看一点：Navidrome 地址必须是每台设备都够得到的，别写 Docker 内部主机名；Folia 页面走 HTTPS 时它也得是 HTTPS，否则浏览器直接拦截混合内容。

排障速查表：常见症状与第一反应

接下来往哪走：分阶段路线图

• 先跑通最小链路：走路线 A，搜一首歌、播放、进入全屏歌词动画，完整走一遍。
• 稳了再接 Navidrome，把自己硬盘里的歌搬上手机。
• 锦上添花：填 AI 密钥让每首歌的主题配色自动生成；部署 sync-server 可以跨设备同步外观，细节见 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