Folia 移动端部署完整指南：如何把全屏歌词动画播放器装进手机主屏幕
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
手机里缺一个能看歌词动画的音乐播放器？Folia 主打全屏歌词动画，支持网易云、QQ 音乐、酷狗等在线音源。本文教你十分钟内把它的 Web 版装进手机主屏幕，点开就是独立 App。
做完你能得到什么
主屏幕多一个 Folia 图标，点它直接全屏启动，没有地址栏。登录任一音源后即可搜索播放，竖屏时歌词动画会按窗口尺寸实时重排。
选一条更轻的路线
| 路线 | 费用 | 技术门槛 | 域名/证书 | 适合谁 |
|---|---|---|---|---|
| 免费平台（Vercel） | 免费 | 低，点按钮即可 | 平台自带 HTTPS | 绝大多数人 |
| NAS 自架（Docker） | 已有设备 | 中，需装 Docker | 需另配反向代理 | 有 NAS 的人 |
| 桌面端 Electron | 免费 | 最低 | 不需要 | 只要电脑用 |
没有设备、只想马上用的，选第一条；家里已有 NAS 且想要私有部署的，选第二条。
照着四步装好第一首歌
- 克隆仓库
git clone https://gitcode.com/GitHub_Trending/fo/folia-major，在 docs/technical.md 找到 "Deploy with Vercel" 按钮，点击创建项目并关联仓库，平台分配一个 HTTPS 地址。 - 在平台的环境变量设置里补：
VITE_NETEASE_API_BASE填你的网易云 API 实例地址，VITE_QQ_API_BASE填/api/qq，QQ_SESSION_SECRET存为 Secret；QQ 变量说明见 docs/qq-music-deployment.md。重新部署后手机浏览器打开该地址，首页正常渲染即成功。 - 安卓 Chrome 点右上角三点菜单，选"添加到主屏幕"或"安装应用"；iPhone Safari 点底部分享图标，选"添加到主屏幕"。看到 Folia 图标出现在桌面即成功。项目 PWA 声明见 vite.config.ts，
display为standalone，iOS 全屏标签已内置，两端无需额外配置。 - 点开图标，选网易云、QQ 音乐或酷狗扫码登录；接 Navidrome 则在账户页填地址与账号。搜到歌、动画开始，全流程结束。
Docker 路线：把 deploy/docker/compose.yaml 和.env.example放入同一目录，.env里填FOLIA_IMAGE_NAMESPACE=papersman，用openssl rand -hex 32生成SYNC_TOKEN（至少八位）；QQ 用户再补QQ_SESSION_SECRET。执行docker compose up -d，浏览器访问http://NAS-IP:18080，细节见 deploy/docker/README.md。
常见问题
- 装不进主屏幕：PWA 安装要求安全上下文，裸 HTTP 站点不满足。改用 HTTPS 地址，安卓用 Chrome、iPhone 用 Safari，刷新一次。
- 重新部署后手机还是旧界面：Service Worker 按 autoUpdate 策略更新，时机不可控。清除一次站点数据，或移除图标后重新添加。
- QQ 音乐入口点不动：serverless 形态缺
VITE_QQ_API_BASE与QQ_SESSION_SECRET两个变量。补齐后必须重新构建部署，该变量是构建时写进前端的。 - Navidrome 自动登录没生效：
NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项只填了部分，或 URL 不是完整 http(s) 地址。补齐三项并确认可从手机直连该地址，再重建 backend 容器。 - 手机想听本地音乐文件：目录导入依赖 File System Access API，只有桌面 Chromium 系浏览器提供，手机浏览器没有入口，替代路线走 Navidrome。
- 弱网能离线吗：界面资源有 Service Worker 缓存，页面能很快打开，但音乐流必须走网络，做不到完全离线。
一条地址、一次添加，Folia 就成了口袋里的全屏歌词动画播放器；换设备时，浏览器里再走一遍"添加到主屏幕"即可。部署细节与环境变量从 docs/technical.md 或 deploy/docker/README.md 入手。
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
