企业官网建设流程全解析

Folia PWA 完整设置指南：15 分钟把歌词动画播放器装进手机

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

Folia 是一款支持网易云、QQ 音乐、酷狗、Navidrome 与本地曲库的歌词动画播放器，没有官方手机 App。官方给出的标准路径是：先部署 Web 版，再把它以 PWA 的形式加进手机主屏幕。跟着本文走一遍，约 15 分钟后你的主屏幕上就多了一个全屏歌词播放器。

先判断：这篇指南适不适合你

适合看：

• 想在手机上用 Folia，且不想自己长期维护服务器的人
• 有 NAS 或服务器，但只想花十几分钟起步的人

不用看：

• 已经在用桌面版的人。桌面版是功能全集，不需要部署 Web 版
• 只打算在手机上导入本地音乐文件夹的人。这条能力手机没有，本文会说明替代方案

先看清边界：Folia 在手机上能做什么、不能做什么

先对照一下你的使用场景，再决定要不要继续装：

主流程：从零到一个能播放的 Folia 地址

主流程走免费托管平台（Vercel / Cloudflare）的一键部署，这是大多数人占比最高的一条路。首次使用要额外准备一个网易云 API 实例，总计约 15 分钟；已有实例的话只要 5 分钟。

第一步：准备网易云 API 地址（仅首次，5~10 分钟）

Web 版不自带网易云接口，VITE_NETEASE_API_BASE是必填环境变量，指向你自己部署的 NeteaseCloudMusicApiEnhanced 实例地址。已经有实例的直接跳到下一步。预期结果：拿到一个可访问的http://你的域名:3000之类地址。

第二步：一键创建项目（约 2 分钟）

在仓库 README 中找到 Vercel 或 Cloudflare 的一键部署入口，点进去授权并等待构建完成。预期结果：得到一个自带 HTTPS 的公网地址（如.vercel.app/.workers.dev结尾的域名）。这一步不需要服务器，也不用配证书。

第三步：补齐环境变量并重新部署（约 3 分钟）

在项目的环境变量里至少填上：

• VITE_NETEASE_API_BASE：第一步拿到的实例地址，必填
• VITE_QQ_API_BASE=/api/qq，外加一个只存在服务端的随机密钥QQ_SESSION_SECRET：想启用 QQ 音乐时填，走仓库内置的 serverless 入口，配置步骤见QQ 音乐部署指南
• VITE_AI_PROVIDER与对应密钥（如GEMINI_API_KEY）：想要 AI 主题配色才填

完整变量表在技术与开发说明里。保存后触发重新部署，预期结果：打开新地址能进入 Folia 首页，搜索能出结果。

第四步：手机上连上验证（约 1 分钟）

用手机浏览器打开地址，登录音乐账号，随便搜一首歌播放。预期结果：播放正常，歌词以全屏动画呈现。

其余两条路各一句话：NAS / 自建服务器用户用 Docker 全栈，从仓库取deploy/docker/compose.yaml与.env.example两个文件放进同一目录，openssl rand -hex 32生成SYNC_TOKEN后执行docker compose up -d --wait即可，约 15 分钟，细节见Docker 部署文档；想完全自定义的按技术与开发说明的环境变量表部署到任意 Node.js 平台（要求 Node.js 24 及以上）。

📱 把 Folia 加进主屏幕：Android 与 iOS 的入口位置

Android（Chrome）

1. 用 Chrome 打开 Folia 地址，确认地址栏有锁形标志
2. 点右上角竖排三点菜单
3. 选"添加到主屏幕"（部分版本显示为"安装应用"）
4. 确认名称为 Folia，点"添加"

装完首次点开会比平时多等几秒钟，这是 Service Worker 在做首次预缓存，属于正常现象，之后再启动会明显更快。

iPhone（Safari）

1. 用 Safari 打开 Folia 地址
2. 点底部中间的分享按钮
3. 向下滑动找到"添加到主屏幕"并点选
4. 确认名称后点"添加"

点开图标后直接进入全屏，没有地址栏。页面已声明apple-mobile-web-app-capable等标签，状态栏采用半透明样式，观感接近原生 App。

竖着拿手机时，歌词主题按窗口尺寸做响应式排版，歌词自动重新分行，动画速度和光效不变。

⚠️ 避坑清单：五件最常碰上的事

1. 菜单里没有"添加到主屏幕"，或者点了没反应现象：找不到安装入口，或页面提示无法安装。 原因：地址不是 HTTPS 安全上下文（典型是局域网 IP 的普通 HTTP），Service Worker 无法注册。 解法：托管平台天然带 HTTPS，一般不受影响；自托管 NAS 用其自带的反向代理加浏览器信任的证书切到 HTTPS，自签名证书不算数，要求见Docker 部署文档的 HTTPS 一节。

2. 切到 HTTPS 后，登录态和设置全没了现象：升级 HTTPS 当天，账号掉线、偏好重置、本地曲库索引消失。 原因：HTTP 与 HTTPS 是两个不同的 origin，IndexedDB 里的数据不会自动迁移。 解法：重新登录、重配一次即可，属预期行为，不是丢数据。

3. Navidrome 曲库连不上现象：设置里填了曲库，加载报错或一直转圈。 原因：Folia 页面是 HTTPS，而NAVIDROME_URL填的是普通 HTTP 地址，被浏览器按混合内容拦截。 解法：给 Navidrome 换一套完整 HTTPS 地址再填。

4. 服务器更新了，手机上还是旧界面现象：部署了新构建，手机图标点进去仍显示旧版。 原因：Service Worker 采用autoUpdate策略，下次打开才生效，长时间不打开可能一直停留在旧缓存。 解法：清除一次站点数据，或删掉图标重新添加到主屏幕。

5. 想在手机上导入手机里的音乐文件现象：设置里找不到文件夹导入入口。 原因：本地导入依赖 File System Access API，只有桌面 Chromium 系浏览器提供，手机端入口被隐藏。 解法：手机上的"自己的歌"走 Navidrome 方案，音乐放 NAS，Folia 当客户端用。

进阶：两个让体验更顺手的玩法

跨设备同步主题。Docker 全栈默认包含独立的 Sync Server（默认端口13000），部署后在 Folia 的"存储设置"里填服务端地址和SYNC_TOKEN，外观设置与 AI 主题库就能在多台设备间同步。不想跑 Docker 的话，Sync Server 也能以 Cloudflare Workers 的 serverless 形态部署。

Navidrome 免登录预置。Docker 用户在.env里填NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项，任何新打开的浏览器第一次进来就自动登录这个 Navidrome，手机不用手动填账号。预置凭据默认只发给局域网来源（NAVIDROME_PRESET_ALLOW=private），建议单独建一个 Navidrome 账号给 Folia 用。

开始前的六项自查

• 地址栏有锁形标志（HTTPS）吗？
• 安卓用的是 Chrome、iOS 用的是 Safari 吗？
• VITE_NETEASE_API_BASE填了，且那个实例现在能访问吗？
• 音乐账号在手机上登录过了吗（登录态按设备保存）？
• 主屏幕图标名称显示为 Folia 吗？
• 接了 Navidrome 的话，曲库地址也是 HTTPS 吗？

收尾

到这里，这台手机已经是一台全屏歌词动画播放器：在线搜索、曲库播放、主题切换都装在一个接近原生 App 的窗口里。想继续提升体验，先看上面"进阶"两节；想要桌面级的完整能力（本地文件夹、模组、壁纸模式），再装一台桌面版即可。

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