企业官网建设流程全解析

Folia PWA 安装完整指南：把歌词动画播放器装进手机

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

这是一份 Folia PWA 手机安装指南：装完之后，你的主屏幕上会多出一个独立的 Folia 图标，点它直接打开一个没有地址栏、没有标签页的全屏播放器，歌词动画铺满整块手机屏幕。Folia 官方没有提供手机 App，但它的 Web 版原生支持 PWA（Progressive Web App，即浏览器把一个网页按应用装到主屏幕的能力），整个流程只需要解决两件事——先备一个稳定的地址，再把它钉上主屏幕。

先看能力边界：手机端的 Folia 能干什么、不能干什么

选部署路线之前先确认能力范围，免得装完发现和预期不符。

手机上完全可用的部分：

• 在线曲库：网易云音乐、QQ 音乐、酷狗均支持搜索与播放，账号登录态保留在手机浏览器里，换设备也不用重复登录
• 歌词动画主题：各风格有独立排版，自动适配竖屏
• Navidrome 私有曲库：家庭 NAS 歌曲在手机上听的主要途径

缺的只有一项：导入本地音乐文件。目录导入依赖 File System Access API（一种只在桌面 Chromium 系浏览器提供的本地目录选择能力），手机浏览器没有这个接口，因此选不了目录。"自己的歌"想听，走下面的 Navidrome 路线即可。

一句话定位：把手机端的 Folia 当成"歌词动画播放器 + 在线 / Navidrome 曲库"来用，体验最顺。

拿到一个手机能打开的 HTTPS 地址：三条路线对号入座

PWA 本质仍是网页，所以第一步是让 Folia 有一个稳定的 HTTPS 地址——HTTPS 是 PWA 可靠安装与离线运行的前提条件。按你手上的资源三选一：

• 一键部署（新手首选）：仓库 README 提供了指向 Vercel 与 Cloudflare 的一键部署按钮，不用自备服务器，平台自带域名与 HTTPS 证书，几分钟就能拿到可访问地址。若要接入 QQ 音乐，配置说明见 docs/qq-music-deployment.md。
• Docker 全栈（NAS / 自建服务器）：新建一个空目录，放入 deploy/docker/compose.yaml 与环境变量模板；编辑.env，把SYNC_TOKEN填成至少八位的随机字符串（可用openssl rand -hex 32生成），执行docker compose up -d启动，默认访问地址为http://NAS-IP:18080。完整步骤与反向代理的 HTTPS 配置见 deploy/docker/README.md。
• 克隆仓库自行部署（完全自定义）：执行git clone https://gitcode.com/GitHub_Trending/fo/folia-major，再按 docs/technical.md 里的环境变量说明，部署到任意支持 Node.js 的平台。

⚠️ NAS 自部署请务必配好反向代理与可信证书。只留 HTTP 地址时，手机上的安装入口可能根本不会出现。

把 Folia 钉上主屏幕：安卓与 iOS 各两步

地址到手后，用对应系统的浏览器打开它，然后走固定路径：

安卓（Chrome）

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

iPhone / iPad（Safari）

1. 用 Safari 打开 Folia 网页
2. 点屏幕底部的分享图标
3. 在面板里找到「添加到主屏幕」
4. 确认名称后点「添加」

完成后主屏幕出现 Folia 独立图标，点开即以全屏独立窗口启动，整块屏幕归歌词动画所有。

这种"原生感"由哪几项配置构成

装完后的体验不是观感问题，而是四件能在仓库里逐条对上的配置：

• vite.config.ts 中的 PWA manifest（声明图标、窗口模式等启动行为的应用信息清单）设置了standalone独立窗口模式、#09090b主题色和 512×512 图标
• index.html 内置apple-mobile-web-app-capable等 iOS 全屏元标签，iPhone 同样拿到完整全屏体验
• 核心界面资源被 Service Worker（浏览器内拦截请求、缓存文件的小程序）预缓存，弱网环境也能快速启动
• Service Worker 采用autoUpdate更新策略，服务端发新版后，下次打开即自动用上最新版

歌词布局本身也随屏幕走：每种动画风格是独立的一套排版与可调参数，窗口尺寸变化时会响应式重排，竖着拿手机时歌词自动换布局。「主题速编」入口可随手换风格，比如「流光」——深色底叠加流动光效；主题配色还能由 AI 按歌曲情绪与歌词内容自动生成，手机端同样可用（前提是部署时配置了 AI 密钥）。

让"自己的歌"出现在手机里：接 Navidrome 的 3 步

手机导入不了音频文件，Navidrome 正好补上这一环，接完即可：

1. 在 NAS 上用 Docker 部署 Navidrome，并挂载音乐目录
2. 在 Folia 的账户页里接入 Navidrome 服务
3. Folia 拉取曲库、封面与歌词，歌词动画照常驱动

这套组合的收益是：音频文件留在 NAS，手机只通过 PWA 远程播放，不占手机存储；歌词还能靠智能匹配自动补齐。本地曲库的管理细节可参考 docs/local-library-management.md（该文档主要面向桌面端导入流程）。

安装前后检查清单：4 个高频问题一次说清

看不到「添加到主屏幕 / 安装应用」入口？先确认地址是 HTTPS（HTTP 下 PWA 无法可靠安装）；安卓请用 Chrome、iOS 请用 Safari，其他浏览器可能不显示入口；再重新加载一次页面——安装提示有时只在首次访问时出现。

更新后手机上还是旧版本？autoUpdate策略下，下次打开就会自动生效。长期未更新时，清除一次站点数据，或移除后重新「添加到主屏幕」。

手机端能像桌面那样导入本地音乐吗？不能。目录导入依赖桌面端独占的 File System Access API，手机端请走 Navidrome 方案。

弱网或地铁里能打开吗？能。核心界面资源在首次加载后已被预缓存，弱网环境照样快速启动；仍然需要网络的是音乐流本身。

走完这条路径的终点始终是一个画面：主屏幕上的 Folia 图标，点开即全屏，歌词动画照常在手机里铺满整屏。最小行动清单四件事：选一路线部署拿到 HTTPS 地址；在手机浏览器里完成「添加到主屏幕」；点图标验证全屏窗口；需要"自己的歌"时部署 Navidrome 并在账户页接入。

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