Folia 安装：从零到第一首歌，十分钟点亮全屏歌词动画

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

Folia 是一款全屏歌词动画播放器：歌词跟着节拍在整个屏幕上起舞，能接本地曲库，也能接网易云、QQ 音乐、酷狗、Navidrome 等音源。Windows、macOS、Linux 三个平台都有对应安装包，顺利的话 5-10 分钟走完下载、安装、启动与第一首歌。

路线速览：十分钟选定 Folia 下载渠道

看系统、看直连，两条信息就能定路线：直连好就选官方安装包，步骤最少；直连差直接走网盘镜像，Linux 用户按发行版选 AUR 或便携版。

💡 网盘入口在 README.md 的「快速下载」一节，官方镜像，转存到自己网盘再下载。想在 NAS 或手机浏览器上跑 Web 版，看 deploy/docker/README.md。

Folia Windows 安装步骤：从网盘到首次启动

准备

1. 打开 README.md 的「快速下载」一节，从 Releases 或官方网盘拿 Windows.exe安装包。
2. 核对文件名里的版本号，确保不是来路不明的转发包。

操作

3. 走网盘就先转存到自己网盘再下载，断了能续传。
4. 双击.exe运行，按向导走完。运行环境已内置，装完即用，不用单独装任何运行库。

验证

5. 双击桌面快捷方式启动；没看到快捷就去开始菜单搜 Folia，在关于页核对版本号。

主界面正常打开、关于页版本与下载文件名一致，本节通过。

Folia macOS 安装步骤与“已损坏”提示处理

准备

1. 从网盘或 Releases 下载 Apple silicon 版.dmg，Intel 版只在 Releases。
2. 核对文件名里的版本号再动手。

操作

3. 打开 dmg，把Folia.app拖进 Applications，别在挂载盘里直接运行。
4. 首次启动弹「已损坏」或「无法验证」，属未签名构建的已知表现。打开终端：

# 移除下载隔离属性，让 Gatekeeper 不再拦截 xattr -dr com.apple.quarantine /Applications/Folia.app

⚠️ macOS 没有应用内自动更新，每次覆盖安装新版本后都要重跑一遍上面这条命令，详解见 docs/desktop/macos-app-damaged.md。

验证

5. 从 Applications 再启动一次，窗口正常弹出、没有拦截弹窗；确认跑的是 Applications 里的版本，不是 dmg 里的挂载版本。

应用无 Gatekeeper 拦截正常启动，关于页版本与下载文件名一致，本节通过。

Folia Linux 安装：AUR 一行命令或便携版

Arch 系（Folia AUR 安装）

1. 确认已装 yay 或 paru。
2. 一条命令装完，alsa-lib、gtk3、nss 等依赖自动解决。

# 用 yay 从 AUR 安装，paru 用户把 yay 换成 paru yay -S folia-major-bin

3. 程序装进/opt/folia-major，在应用菜单点folia-major启动。依赖清单与安装位置定义在 packaging/aur/folia-major-bin/PKGBUILD。

其他发行版（Folia 便携版）

1. 从 Releases 页下载folia-major-<版本>-linux-x64.tar.gz。
2. 解压到任意目录，运行./folia-major；可执行文件和resources/留在同一目录，别只挪其中一个。
3. 把包内resources/linux/folia-major.desktop模板复制到~/.local/share/applications/。
4. 把__APP_PATH__、__ICON_PATH__占位符替换为实际路径；桌面环境有要求就把文件标记为可信。完整流程见 packaging/linux/README-LINUX.txt。

⚡ AUR 构建从 Releases 拉包慢时，先手动下好同版本 tar.gz 放进 AUR 源码目录，再本地构建：

# 本地构建并安装 AUR 包 makepkg -si

Folia 正常启动、关于页版本与下载文件名一致，本节通过。

首跑验收：确认 Folia 歌词播放器可用

播放一首带歌词的歌，然后逐条对照打勾，这是 Folia 安装的最小闭环：

• 能启动：双击快捷方式或应用菜单入口，主界面正常出现。
• 版本对得上：关于页显示的版本号与下载文件名里的数字一致。
• 核心闭环：播放一首带歌词的歌，进入全屏歌词动画。
• 风格切换：到设置里换一种视觉风格。

排错速查：Folia 安装常见问题

下载慢或断流→ 国际直连质量差 → 换官方夸克 / 百度网盘镜像；断了用网盘续传，不用重下。镜像只含 Windows 与 Apple silicon 包，Linux 包继续走 Releases，或先手动下好压缩包再本地构建 AUR 包。

Folia Linux 黑屏、透明度异常或启动即闪退→ GPU 兼容问题 → 先按软件渲染验证：

# 以 swiftshader 软件渲染模式启动 FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major

仍不稳定就把取值改为software走最保守的软件渲染；system恢复系统图形路径。变量说明见 packaging/linux/README-LINUX.txt。

macOS 提示「应用已损坏」或「无法验证」→ 当前构建缺少 Developer ID 签名与公证，下载文件带隔离属性 → 跑一遍 macOS 步骤里的xattr命令，再从 Applications 重新打开。

网盘包版本比最新旧→ 镜像同步滞后 → 把文件名里的版本号与 Releases 最新值比对，不一致就等同步或改走直连。

装完登录任一在线音源，或指向一个本地音乐文件夹。第一首歌播下去，全屏歌词动画就亮起来了 🎵

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