企业官网建设流程全解析

Folia Web 部署指南：把全屏歌词动画播放器装进手机主屏

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

Folia 是一款以全屏沉浸式歌词动画为核心的在线音乐播放器，支持网易云、QQ 音乐、酷狗在线搜索播放，也支持 Navidrome 自建曲库与本地音乐库，还能用 AI 按歌曲内容生成主题配色。本文只讲 Web 版：部署上线后，你无需安装任何第三方安装包，就能从手机主屏一键拉起全屏界面，没有地址栏，歌词动画直接铺满整块屏幕。

完成后的效果长什么样

先看收获。上线后在手机上打开，主界面是干净的曲库与搜索入口，点歌即播：

播放开始后，整块屏幕就是歌词动画本身。每个主题都有独立的排版氛围与可调参数，竖屏下自动响应式适配，不裁剪也不拥挤：

动手前：先确认这三件事

部署本身不难，难的是前提没满足时「安装到手机」这一步会直接消失。对照确认：

1. 部署地址必须是 HTTPS。Service Worker 只在可信安全上下文里可靠运行，这是 PWA 安装与离线能力的基础；自签名证书不算可信，装了也没用。
2. 手机浏览器限定 Chrome for Android 或 iOS Safari，其他浏览器的菜单里没有 PWA 安装入口。
3. QQ 音乐播放前必须先扫码登录。登录态保存在手机浏览器本地，一次扫码后长期有效，不会每次重扫。
4. 应用只挂在域名根路径。不支持把站点挂到/folia/这类子路径下，托管时不要加前缀路由。

移动端 Web 版能做什么、不能做什么，一张清单说清：

• ✅ 网易云 / QQ 音乐 / 酷狗在线搜索与播放，各平台入口齐全
• ✅ 全屏歌词动画，多主题竖屏响应式适配
• ✅ Navidrome 流媒体自建曲库（依赖外部 Subsonic 服务）
• ✅ AI 按歌曲内容生成主题配色（部署侧配置 AI 密钥后生效）
• ❌ 本地音乐目录导入 / 重扫 —— 依赖 File System Access API，目前仅桌面 Chromium 系浏览器支持，手机端浏览器没有这个 API
• ❌ Folium 模组系统（歌词动画扩展、播放页图层）—— 实验性功能，仅在桌面端「设置 → 模组」提供

没有服务器也能上线吗：三条路线从易到难

三条路线信息点一致，区别只在谁来跑服务。挑一条跟下来即可。

路线一：一键托管，几分钟拿到 HTTPS 地址

前提条件：一个 Vercel 或 Cloudflare 账号。平台拉取代码并构建，约几分钟产出带 HTTPS 的公网地址，适合只想在手机上听歌的场景。

1. 在仓库 README 中点 Vercel 或 Cloudflare 的一键部署按钮，创建项目。
2. 到平台项目的环境变量设置中补齐配置：至少填VITE_NETEASE_API_BASE（网易云 API 实例地址，必填）；需要 AI 主题再加VITE_AI_PROVIDER（取值google或openai）与对应密钥GEMINI_API_KEY或OPENAI_API_KEY，完整取值示例见环境变量说明。
3. 想用 QQ 音乐：VITE_QQ_API_BASE填/api/qq，再配一个服务端密钥QQ_SESSION_SECRET。不要给它加VITE_前缀——带前缀的变量会被编译进前端资源，而登录态密钥只能留在服务端。这套内置 serverless 入口支持微信扫码与手机 QQ 扫码，细节见QQ 音乐部署指南。
4. 酷狗在此路线下需自行部署一个 KuGouMusicApi 实例并填VITE_KUGOU_API_BASE；留空则酷狗入口不可用。

完成自检：部署完成后打开公网地址，能搜到歌并正常播放，即上线成功。

路线二：家里有 NAS？Docker Compose 一条命令拉全栈

前提条件：Docker Engine 24 及以上、Compose v2。不需要下载仓库源码，只需要两个文件。

1. 新建空目录，放入Compose 文件与环境变量模板，后者改名为.env。
2. 执行openssl rand -hex 32，把输出填进.env的SYNC_TOKEN（至少 8 位，必填，用作 Sync 客户端的鉴权令牌）。
3. 依次执行docker compose config、docker compose pull、docker compose up -d --wait。

完成自检：docker compose ps显示全部服务 running；浏览器访问http://NAS-IP:18080看到界面即 Web 栈活了，Sync Server 健康检查在http://NAS-IP:13000/health。网易云、酷狗、QQ 均无宿主机端口，只能经 gateway 访问。

两个收尾动作：

• 供手机 PWA 用必须套 HTTPS：给 18080 端口挂 NAS 自带的反向代理加可信证书。代理需透传Host、X-Forwarded-Host、X-Forwarded-Proto、X-Forwarded-For；若代理跑在宿主机上，把FOLIA_HTTP_BIND、FOLIA_SYNC_BIND改为127.0.0.1防止绕过。
• 更新与回滚：docker compose pull && docker compose up -d（Docker 不会自动拉取新镜像）；回滚时在.env把FOLIA_STACK_VERSION固定到先前的A.B.C标签。完整说明见Docker 部署文档。

路线三：完全自建，克隆仓库自己发

前提条件：Node.js 24 及以上（项目engines的硬性要求）。

1. 执行git clone https://gitcode.com/GitHub_Trending/fo/folia-major。
2. 执行npm install。
3. 执行cp .env.example .env.local，按技术文档的环境变量表填齐网易云 API 地址、可选的酷狗 / QQ 地址与 AI 密钥。注意VITE_开头的变量在构建时写入前端，改完必须重新构建部署才生效。
4. 执行npm run build，把构建产物发布到任意支持 Node.js 的平台即可。

完成自检：访问你发布的地址，搜索并播放一首歌，界面与托管路线一致。

怎么把 Folia 装到手机主屏

Android（Chrome）：打开 Folia 的 HTTPS 地址 → 右上角菜单（⋮）→ 选「安装应用」或「添加到主屏幕」→ 确认名称为 Folia 后添加。

iPhone（Safari）：打开地址 → 底部「分享」按钮 → 上滑找到「添加到主屏幕」→ 确认名称后添加。

点击主屏图标，窗口直接全屏拉起：没有地址栏与标签页，状态栏与应用融为一体，竖屏下各主题排版自动适配，全程不需要下载任何安装包。

进阶：把自己的曲库接进来

原理一句话：音频文件留在 NAS，Navidrome 扫描后以流媒体方式对外服务，手机 PWA 只拉取曲库、封面和歌词，不占手机存储，也不额外花流量。

1. 在 NAS 上用 Docker 部署 Navidrome 并挂载音乐目录。
2. 在 Folia 的账户页接入 Navidrome，填一个每台设备都够得到的地址——不能写 Docker 内部主机名，外部设备访问不到。
3. 协议必须对齐：Folia 页面走 HTTPS 时，Navidrome 地址也必须走 HTTPS，否则浏览器按混合内容直接拦截。
4. 走 Docker 路线的话，在.env里同时填NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD，新打开的浏览器会自动登录并启用（建议单独建一个 Navidrome 账号给 Folia 用）；曲库与封面同步完成后直接播放，缺失歌词可走智能匹配自动补齐。

改过.env里的 Navidrome 配置后，执行docker compose up -d --force-recreate backend让预置生效。

出问题时：对照自救

浏览器菜单里没有「添加到主屏幕」？最常见原因是访问的是 HTTP 地址，或当前浏览器不是 Chrome / Safari。换成 HTTPS 地址后重新加载页面即可。

部署更新了，手机上还是旧界面？Service Worker 的 autoUpdate 一般下次打开才生效，偶尔会卡住。清除站点数据，或删掉主屏图标重新添加。

Navidrome 连上了但曲库加载不出来？大概率是地址填了 Docker 内部主机名（外部设备够不到），或页面是 HTTPS 而 Navidrome 是 HTTP。改为各设备可达的地址，必要时把协议对齐到 HTTPS。

切到 HTTPS 后登录态和设置全丢了？HTTP 与 HTTPS 属于两个不同 origin，IndexedDB、登录态、设置不会自动迁移。重新登录并核对配置，之后不要来回切换协议。

Navidrome 预置登录没生效？.env里三项只填了一两项，或NAVIDROME_URL不是完整的 http(s) 地址（backend 日志会有警告）。三项补齐后执行docker compose up -d --force-recreate backend。

托管路线下酷狗入口不可用？该路线没有内置酷狗服务，VITE_KUGOU_API_BASE留空时入口就是不可用的。部署一个 KuGouMusicApi 实例、填上变量并重新构建即可。

上线前最后检查一遍

• 部署地址为 HTTPS，且手机浏览器是 Chrome（Android）或 Safari（iOS）——两者缺一，安装入口不会出现。
• Docker 路线以docker compose ps全部 running 为准；改过.env后按Docker 文档对相应容器执行--force-recreate。
• Navidrome 地址对所有设备可达，且与 Folia 页面协议一致。
• 托管路线的VITE_变量改动后已重新构建部署，密钥类变量（QQ_SESSION_SECRET）没有误加VITE_前缀。

下一步建议：先用托管路线接一个在线曲库，把「安装 → 扫码登录 → 播放 → 全屏歌词动画」完整走一遍，稳定后再上 Navidrome 补入自己的歌。至于手机端做不了本地目录导入，这不是故障，而是它的设计归宿在桌面端，本地曲库管理的完整能力都留在那里。

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