Folia 歌词动画播放器 10 分钟安装教程：Windows、macOS、Linux 全平台装好并跑通

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

Folia 是一款全屏沉浸式歌词动画播放器，支持网易云、酷狗、QQ 音乐、Navidrome 和本地音乐库，提供 Windows、macOS、Linux 桌面版。这篇 Folia 安装教程覆盖三大平台，国内网络从 GitHub Releases 下载慢、各系统装法不同——照着做，十几分钟装好并确认能放歌。

十秒选路：你的系统装哪个

• Windows / macOS：装官方安装包，.exe或.dmg，全程鼠标点击。
• Arch / Manjaro：一条命令走 AUR。
• Debian / Ubuntu / Linux Mint：.deb原生包。
• Fedora / RHEL / openSUSE：.rpm原生包。
• 其他 Linux：tar.gz便携版，解压即用。

下载前：选包与核对版本号

去官方 Releases 页取全平台安装包。国内网络直连慢，可走网盘镜像，但网盘只提供 Windows 和 Apple silicon 的正式版，.deb、.rpm、tar.gz得回 Releases 页拿。

包名有规律，以0.7.23为例：

• Windows：Folia-Setup-0.7.23.exe
• macOS Apple 芯片：Folia-0.7.23-arm64.dmg
• macOS Intel：Folia-0.7.23-x64.dmg
• Linux：folia-major-0.7.23-linux-x64.deb/.rpm/.tar.gz

下载完先看一眼文件名里的版本号。Releases 分 Realeco 正式版（latest）、Limo 夜更、Cielo 金丝雀三个通道，新手认准latest标签即可，细节见 docs/technical.md。

先别急：网盘镜像可能比 Releases 慢一个版本，装之前对一下两边版本号，别拿旧包。

Windows 安装 Folia 桌面版

打开安装包对应的下载入口，选Folia-Setup-<版本>.exe，双击后按向导一路下一步。

装完检查两处：开始菜单、桌面有没有 Folia 图标。点一下图标启动，主窗口打开、界面正常显示不是黑屏——硬标准：主窗口能完整显示首页界面，而不是停在黑屏。

macOS 安装 Folia 并处理「已损坏」提示

先确认芯片：Apple 芯片选Folia-<版本>-arm64.dmg，Intel 选-x64.dmg。打开 dmg，把Folia.app拖进「应用程序」，别在挂载盘里直接运行。

首次打开若被系统拦截，提示「已损坏 / 无法验证」，这不是包坏了，是当前版本没有 Apple 开发者签名触发 Gatekeeper。打开「终端」，执行下面这条命令移除下载隔离属性：

xattr -dr com.apple.quarantine /Applications/Folia.app

执行完回到「应用程序」重新启动。硬标准：终端能列出Folia.app目录内容，启动应用不弹任何报错。

先别急：macOS 版没有应用内自动更新，每次覆盖安装新版本后隔离属性会回来，这条命令要再执行一次。完整排查见 docs/desktop/macos-app-damaged.md。

Arch / Manjaro 用 AUR 安装 Folia

确认 AUR helper 可用：终端敲yay --version能打印版本号就行，用paru的换成paru --version。然后一条命令装好：

yay -S folia-major-bin

AUR 构建会从 Releases 拉取同版本tar.gz，程序解包进/opt/folia-major，生成/usr/bin/folia-major命令和桌面菜单项。依赖alsa-lib、gtk3、libxss、nss，构建前可对照 PKGBUILD 核对版本。

硬标准：which folia-major输出/usr/bin/folia-major，应用菜单里多出 folia-major 启动项。

在 Debian / Ubuntu 上安装 .deb 包

从 Releases 下载folia-major-<版本>-linux-x64.deb，用下面命令安装：

sudo dpkg -i folia-major-*.deb

若提示依赖缺失，别删包重装，接着执行这句补齐依赖：

sudo apt -f install

硬标准：dpkg -s folia-major输出状态为install ok installed，应用菜单出现 Folia。

在 Fedora / openSUSE 上安装 .rpm 包

下载folia-major-<版本>-linux-x64.rpm后用 dnf 安装，./前缀不能省：

sudo dnf install ./folia-major-*.rpm

少了./，dnf 会去在线仓库找包然后报「找不到」。

硬标准：rpm -q folia-major打印出folia-major-<版本>。

其他 Linux 发行版用 tar.gz 便携版

下载folia-major-<版本>-linux-x64.tar.gz，解压到固定目录，例如~/Apps/Folia/，进入该目录直接运行：

./folia-major

主窗口弹出来，硬标准：终端无报错且 Folia 主窗口正常显示。

启动黑屏、透明度异常或闪退，多半是 GPU 渲染路径不兼容，切软件渲染再试：

FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major

仍不稳定就用最保守的FOLIA_LINUX_GRAPHICS_MODE=software ./folia-major。想加常驻启动项，把包内resources/linux/folia-major.desktop复制到~/.local/share/applications/，替换其中__APP_PATH__、__ICON_PATH__两个占位符为实际绝对路径，模板说明见 packaging/linux/README-LINUX.txt。

装完 Folia 后的三步跑通流程

装上了不等于跑通了，按顺序走三步，全过才算真正能用：

1. 打开主窗口——界面正常显示，不是黑屏。
2. 连上一个音源——导入本地音乐文件夹，或登录任一在线源，点开任意一首歌。
3. 点播放——全屏歌词动画随节奏渲染出来，走到这里就算跑通了。

全屏歌词不止一种排版，内置多个主题可切换，风格参考 img/preview-tilt.png 这类预览。

装完 Folia 遇到报错怎么办

问：Linux 启动黑屏、透明度异常或闪退？切软件渲染：FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major，仍不稳再改software。

问：macOS 说「已损坏」？未签名触发 Gatekeeper 拦截，执行xattr -dr com.apple.quarantine /Applications/Folia.app移除隔离属性。

问：AUR 构建卡在 Releases 下载？手动下好同版本tar.gz放进构建源码目录，再执行makepkg -si跳过下载继续构建。

问：.deb装完提示依赖缺失？sudo apt -f install一次补齐，这是正常现象。

问：网盘里的包和最新版本对不上？镜像滞后了，以 Releases 页latest的版本号为准重新选包。

Linux 桌面端细节（Wayland、遥控窗等）可继续看 docs/technical.md。装好跑通之后，全屏歌词动画就属于你了 🎵

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