Folia 全屏歌词动画播放器安装与部署指南

发布时间：2026/10/29 1:25:52

Folia 全屏歌词动画播放器安装与部署指南

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

Folia 是一款全屏歌词动画播放器，把歌词渲染成覆盖整个屏幕的文字动画，音源覆盖网易云、QQ 音乐、酷狗、Navidrome 与本地音乐库。读完本文，可完成桌面版安装（Windows / macOS / Linux）或 Docker 自托管部署，并验证全屏歌词动画正常渲染。

选路

若以电脑桌面听歌、追求沉浸式全屏歌词动画为主，走桌面版安装。
若要在 NAS 或服务器上自托管 Web 版、供手机浏览器访问，走 Docker 自托管部署。
若已有 Navidrome 服务器，两种形态均可挂接为音源，不构成路线独占。
若无法判断，默认选择桌面版：安装动作最少，Web 版后续可再补。

桌面版安装（Windows / macOS）

打开仓库根目录 README.md 的「快速下载」一节，取对应系统的安装包：Windows 为.exe安装包，macOS 为.dmg镜像。该节同时提供网盘与 Releases 两条下载途径。
运行安装程序或挂载镜像完成安装。注意两点：网盘镜像仅覆盖 Windows 与 Apple silicon 两个正式版安装包，Intel Mac 需改用 Releases 中的 Linux 便携包路线；下载前核对版本号，网盘镜像可能落后于最新发布。
首次启动后，在首页搜索平台名称完成账号登录，或直接打开本地音乐库导入音频目录。随后播放任意歌曲，全屏歌词动画渲染出来即表示安装完成。

Linux 安装

Arch（AUR 助手）

已安装yay或paru时，执行：

yay -S folia-major-bin

助手会自动处理依赖（alsa-lib、gtk3、libxss、nss），应用部署到/opt/folia-major并生成桌面项。若构建卡在从 Releases 拉取folia-major-<版本>-linux-x64.tar.gz这一步，则改走下方便携包路线，自行控制下载进度。

通用发行版（便携包）

从 Releases 取linux-x64.tar.gz，解压到固定目录（如~/Apps/Folia/，避免临时目录）。
将包内resources/linux/folia-major.desktop复制到~/.local/share/applications/。
编辑复制出的文件，把__APP_PATH__与__ICON_PATH__两处占位符替换为实际绝对路径；步骤示例见 packaging/linux/README-LINUX.txt。

应用菜单中出现folia-major并成功启动、首页可正常浏览，即安装成功。

自托管部署（Docker）

部署不需要源码，只需两个文件，要求 Docker Engine 24+ 与 Compose v2：

新建空目录，从 deploy/docker/ 取compose.yaml与.env.example两个文件放入（后者重命名为.env）。
执行openssl rand -hex 32生成随机串，填入.env的SYNC_TOKEN（至少 8 位，同步服务必填）。
执行docker compose up -d启动。
浏览器访问http://<服务器地址>:18080打开 Web 版；Sync Server 健康检查在 13000 端口。

在线音源 API 与 Folia Web API 同网关运行，无需为每个平台单独起服务；Navidrome 预置账号等其余环境变量见 deploy/docker/README.md。

验收清单

在线音源（网易云 / QQ 音乐 / 酷狗）登录成功，或本地目录已导入。
播放任意歌曲，全屏歌词动画正常渲染。
同目录同名.lrc/.vtt等歌词文件被自动识别。
本地歌曲的封面与歌词被在线补全。

常见问题

Linux 启动后黑屏或透明度异常？

多为 GPU 路径问题。先以软件光栅化模式启动：FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major；仍不稳定则用FOLIA_LINUX_GRAPHICS_MODE=software走最保守的软件渲染。同时确认可执行文件与resources/目录仍在同一便携包内——目录被拆开会导致各种异常。这些变量只影响 Linux 桌面端启动参数，不改变 Web 版或同步服务配置。

下载缓慢、构建卡顿或版本对不上？

Releases 下载慢时，改用便携包路线手动部署，自行控制下载进度。注意网盘镜像不包含 Intel Mac 与 Linux 包，这两类用户只能走 Releases；下载前与 README 核对版本号，确保拿到最新安装包。

更深的部署细节与环境变量、Linux 渲染机制与 Wayland 壁纸模式见 docs/technical.md，本文范围到此为止。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考