从安装到全屏歌词亮起来:5 分钟跑通 Folia 逐字歌词动画的完整步骤

从安装到全屏歌词亮起来:5 分钟跑通 Folia 逐字歌词动画的完整步骤

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

Folia 把歌词渲染成全屏动画:播放时逐字点亮、整屏滚动,支持网易云、QQ 音乐、Navidrome 与本地音乐库。跟着本文走四步——查设备、挑路线、装完验证、过一遍排障——你手里就是一台能播逐字歌词动画的 Folia。

动手前的 4 项前置要求

1. 架构要 x64。Windows / macOS / Linux 的发布包都只覆盖 x64,macOS 的 Apple silicon 则对应 arm64。Linux 敲uname -m看结果,macOS 打开「关于本机」看。
2. 版本对得上。桌面仓库当前版本 0.7.21,AUR 包固定在 0.1.4,下完包先看文件名里的版本号。
3. 磁盘留够。Linux 解压后建议 1.5 GB 以上,df -h看一眼可用容量。
4. 按路线确认工具。Docker 自托管要 Docker Engine 24+ 与 Compose v2,各敲一次docker version和docker compose version;走 Web 源码部署则需 Node.js 24 及以上,用node -v确认。桌面安装包内置运行环境,不需要 Node,也没有别的依赖。

先定路线,再看步骤

拿不准就走第一条,走不通再回来换路线。

主路线:一键安装包,5 分钟跑通

第 1 步:从 Releases 取对应平台的包

Windows 取.exe,macOS 取.dmg(Apple silicon 选 arm64)。国内直连慢,就用 README「快速下载」里的夸克网盘或百度网盘镜像,提取码flia。镜像只覆盖 Windows 与 Apple silicon 两个正式版,所以取完先对一眼版本号,确认是 0.7.21 再装。

第 2 步:安装程序落盘

Windows 在默认安装目录跑完安装,macOS 把应用拖进Applications/。

第 3 步:启动,确认顶栏出现搜索框

打开 Folia,主界面正常加载、顶栏出现搜索框,说明安装没问题;打不开就跳到「常见问题」第 4 条。

其余三条路线:各三个差异点

Arch / Manjaro:AUR 一条命令装完

与主路线相比只有三处不同。

1. 取包方式不同:不下载文件,直接敲命令。

yay -S folia-major-bin # paru 同名可用

2. 装完位置固定:程序在/opt/folia-major,命令链接在usr/bin/folia-major,菜单项与图标由包自带,不用手工处理。
3. 版本要留神:包内 release 与最新 release 可能不一致,装完顺手看一眼;构建卡在下载步骤就别干等,转手动部署。

依赖alsa-lib、gtk3、libxss、nss可逐项核对 PKGBUILD。

其他 Linux 发行版:解压 tar.gz,再补一个桌面项

1. 取包不同:按发行版选.deb(Debian / Ubuntu)、.rpm(Fedora / RHEL 系)或linux-x64tar.gz,解压到自定目录。
2. 桌面项要手工建:便携包里只有三样——folia-major可执行文件、resources/linux/icon.png、resources/linux/folia-major.desktop模板。把模板复制到~/.local/share/applications/folia-major.desktop,再把文件里的__APP_PATH__、__ICON_PATH__替换成对应绝对路径;桌面环境要求时把文件标记为可信。
3. 目录别拆散:可执行文件与resources/必须留在同一目录,分开就会缺图标、缺启动项模板。

完整步骤见 Linux 打包说明。

Docker 自托管:拉 Web 全栈,多端访问

1. 前置不同:先确认docker version是 Docker Engine 24+、docker compose version为 Compose v2。
2. 取包不同:把 compose.yaml 与环境变量模板 .env.example 放进同一个空目录,先生成 token:

openssl rand -hex 32

3. 验收不同:输出填入.env的SYNC_TOKEN(至少 8 位),然后拉起容器:

docker compose up -d --wait

浏览器打开http://服务器IP:18080出现 Web 首页,Sync Server 健康接口http://服务器IP:13000/health返回正常,即装好。同步数据默认写./data/sync。浏览器里访问本地音乐库依赖可信 HTTPS 上下文,证书与反向代理要求见 Docker 部署文档。

跑起来的样子:3 条验收

• 登录一个音源(如网易云),搜索并点开一首带逐字歌词的歌,歌词随进度逐字点亮、整屏滚动
• 底部进度条与歌词同步推进,换一首歌继续生效
• 把自己的歌导进来:本地文件夹导入音乐库后再播一遍,效果一致

出现黑屏、透明或模糊,不用逐项自查,直接看「常见问题」第 1 条。

常见问题:4 个高频故障

问:Linux 下黑屏、透明度或模糊、闪烁,怎么办?答:先试这条(命令原样保留):

FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major

仍不稳再退到最保守的软件渲染:

FOLIA_LINUX_GRAPHICS_MODE=software ./folia-major

该变量只改 Electron 在 Linux 的启动参数,不影响 Web 端与同步服务。

问:下载慢或中途掉线,怎么办?答:先换成 README「快速下载」的网盘镜像,取完核对版本号;AUR 构建卡在下载步骤同理,转手动部署。

问:行为和预期不一样,是不是版本混了?答:先确认手头装的是哪个版本:AUR 包固定 0.1.4,桌面仓库版本 0.7.21,两者不一致。

问:打不开应用,是不是权限问题?答:macOS 首次打开被 Gatekeeper 拦截,按系统提示授权即可;Linux 下.desktop文件需要被桌面环境标记为可信。

接下来做两件事

登录音源连上网,或把本地文件夹导进音乐库,给全屏动画找点内容。

• 本地音乐库管理:导入、重扫与在线匹配
• Linux 打包说明:桌面项、壁纸模式与图形变量
• Docker 部署文档:环境变量、NAS 反向代理与 HTTPS 证书

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