Folia 歌词动画音乐播放器全平台安装指南：Windows、macOS、Linux 四条路径一次装好

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

Folia 是一款把歌词渲染成全屏动画的音乐播放器，支持网易云、酷狗、QQ 音乐、Navidrome 和本地音乐库五种音源，提供 Windows、macOS、Linux 三套桌面版。下面按系统走一遍完整安装流程，每条路径都能独立走通。

先定路径：我的系统该走哪条安装渠道

记住两条：网盘镜像只有 Windows 与 Apple silicon 两个包，其余平台一律去仓库 Releases 页面取包；网盘版本可能比最新 release 慢一拍，下载前对一眼版本号。

Windows：下载 exe 安装包三步完成

1. 打开仓库 Releases 页面，下载最新的 Windows.exe安装包；外网速度太慢就去 README 的「快速下载」一节，夸克网盘与百度云两条镜像都在那里（百度提取码flia）。
2. 双击安装器，按提示完成安装。
3. 从开始菜单启动 Folia，能进首页即成功。

⚠️ 网盘与 Releases 装出来完全一样，只是取包位置不同；链接失效或版本过时，以 README 里最新的镜像链接为准。

macOS：拖入 Applications 后一条 xattr 收尾

1. 在 Releases 页面按芯片选包：Apple silicon 取arm64的 dmg，Intel 取 x64 包。网盘镜像只放 Apple silicon 版，Intel Mac 没有捷径，直接走 Releases。
2. 挂载 dmg，把Folia.app拖进Applications，别在挂载盘里直接运行。
3. 首次启动被 Gatekeeper 拦下时，打开终端执行：

xattr -dr com.apple.quarantine /Applications/Folia.app # 移除浏览器下载时附带的隔离属性

⚠️ 当前 macOS 版没有 Apple Developer ID 签名与公证，Gatekeeper 拦截是正常现象；应用内也没有自动更新，每次覆盖重装后都要再跑一次上面的命令。

Linux：便携包手动部署（任何发行版通用）

1. 在 Releases 页面下载形如folia-major-<version>-linux-x64.tar.gz的包，解压到固定目录：

mkdir -p ~/Apps/Folia tar -xzf folia-major-*-linux-x64.tar.gz -C ~/Apps/Folia # 整套程序放进固定目录，不要换位置

2. 双击可执行文件folia-major即可启动；想进应用菜单，再补一步桌面项：

cp ~/Apps/Folia/resources/linux/folia-major.desktop ~/.local/share/applications/ # 把桌面项模板复制进用户应用目录

3. 打开复制出的.desktop文件，替换两处占位符：__APP_PATH__填folia-major可执行文件绝对路径，__ICON_PATH__填resources/linux/icon.png绝对路径。
4. 桌面环境有要求时，把该.desktop标记为可信。

便携包里只有三样东西：可执行文件、图标、桌面项模板。排查问题时先确认这三样在同一目录。

Arch 系：AUR 一条命令装预编译包

yay -S folia-major-bin # 从 Releases 拉 linux-x64 包，装进 /opt/folia-major

用paru的把命令名换掉即可。包会建/usr/bin/folia-major软链接，装完从应用菜单启动。

⚠️ AUR 当前包版本为 0.1.4，依赖alsa-lib、gtk3、libxss、nss，可在 packaging/aur/folia-major-bin/PKGBUILD 逐项核对。构建本质是下载 release 的 tar.gz，卡在下载步骤多是网络问题，直接放弃 AUR 转上面的便携部署。

启动验证与界面初印象

启动后能进主界面就算装好了：顶部是 Playlist / Radio / Album / Folder 标签加搜索框，点进任意歌曲，全屏歌词动画才是 Folia 的主场。

本地库也是一等公民：导入音频文件后自动读取元数据、同目录歌词与封面，还能经网易云、QQ 音乐或酷狗补全歌曲信息。

歌词动画有多种主题可切换，排版氛围各不相同：

高频故障速查：从隔离拦截到黑屏

macOS 提示「应用已损坏」原因：无签名无公证，下载带上com.apple.quarantine属性，Gatekeeper 显示成"损坏"。 解法：确认跑的是Applications里的Folia.app而不是挂载盘里的临时版本，再执行一次上文的 xattr 命令。

Linux 黑屏、透明度异常或 GPU 崩溃原因：图形路径不兼容，不是装坏了。 解法：强制软件渲染启动：

FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major # 软件渲染，先试这一档

仍不稳定就换最保守档位：

FOLIA_LINUX_GRAPHICS_MODE=software ./folia-major # 最保守的软件渲染

恢复系统图形路径设FOLIA_LINUX_GRAPHICS_MODE=system。

AUR 构建卡在下载步骤原因：拉 release 的 tar.gz 要走外网。 解法：放弃 AUR，走便携包手动部署。

延伸阅读

• docs/technical.md：Linux 图形模式、Wayland / Hyprland 遥控窗等桌面端细节
• packaging/linux/README-LINUX.txt：便携包组成、壁纸模式与全部启动变量说明
• deploy/docker/README.md：Docker Compose 全栈部署 Web 版本 🎧

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