Folia 下载与安装：5 分钟点亮全屏歌词动画的完整指南
项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major Folia 是一款开源音乐播放器，核心卖点是全屏动态歌词动画：歌词会像文字 PV 一样跟着旋律动，QQ 音乐、网易云、酷狗、Navidrome、本地音乐文件夹都能接进来。这篇下载与安装指南按「先选包 → 走最短路径 → 绕开平台坑 → 核对成功信号」推进，零基础也能照着装完并自己确认没装错。
先花 10 秒确认：你要装哪个
桌面版提供 Windows / macOS / Linux 三种安装包，文件名里写死了系统和架构，下载前问自己三个问题：
- 我的系统是什么？ Windows → 拿
Folia-版本号.exe安装向导；macOS → 拿.dmg磁盘镜像；Linux → 拿folia-major-版本号-linux-x64.tar.gz压缩包（另有 .deb / .rpm）。 - Mac 是什么芯片？ Apple 芯片（M1/M2/M3…）选
arm64，Intel 选x64，下错了打不开。 - 版本号对得上吗？ 文件名里的版本号要和下载页面标注的最新版本一致；国内网络用网盘镜像的话，镜像偶尔落后官方一拍，拿到手先对一眼版本再开工（网盘只覆盖 Windows 和 Apple 芯片 Mac 的正式版）。
包都集中在 Releases 页面，按上面的规则挑一个就行。下面以 Windows 为主线走最短路径，其他平台读者可以跳过有差异的步骤，到「各平台最容易卡住的点」对照自己的系统看。
最短路径：装好 Folia 只需 3 步
- 下载：从 Releases 页面拿到对应系统的安装包（Windows 就是
Folia-Setup-版本号.exe），下载前和页面标注的最新版本号对一眼。 - 安装：Windows 双击运行，向导自带中文界面，安装位置用默认即可，一路点到底；macOS 把 dmg 窗口里的
Folia.app拖进 Applications；Linux 解压到任意目录（如~/Apps/Folia/）。安装包把运行环境整个打了进去，机器上不用预装 Node.js 之类的开发工具。 - 启动：Windows 点桌面或开始菜单的 Folia 快捷方式进主界面；macOS 从 Applications 打开；Linux 直接运行解压目录里的
folia-major可执行文件。
各平台最容易卡住的点
macOS：被提示「Folia.app 已损坏，无法打开」≠ 包坏了
当前发布的 macOS 版本还没有 Apple Developer ID 签名与公证，浏览器下载会带上隔离属性，Gatekeeper 就把未签名应用拦成「已损坏」。打开终端跑一条命令即可，它的作用是移除应用的下载隔离属性：
xattr -dr com.apple.quarantine /Applications/Folia.app
执行完从 Applications 重新打开就进去了。三个细节别漏：先把 app 拖进 Applications 再执行命令，别在挂载窗口里直接运行；macOS 版暂不支持应用内自动更新，以后每次覆盖安装新版本，这条命令都要再跑一遍；如果弹的是别的拦截文案（比如只有「无法验证」），仓库里有针对各种提示的完整处理办法：docs/desktop/macos-app-damaged.md。
Linux：解压即跑，Arch 一条命令装好
通用发行版（Ubuntu、Debian、Fedora 等）解压后运行 folia-major 就能跑。想让应用菜单里也有入口：把包内 resources/linux/folia-major.desktop 复制到 ~/.local/share/applications/，再把文件里的 __APP_PATH__ 和 __ICON_PATH__ 两个占位符替换成可执行文件与图标的实际路径，桌面环境若要求就把文件标记为可信。完整示例见 packaging/linux/README-LINUX.txt。
Arch 用户直接装 AUR 预构建包，依赖（alsa-lib、gtk3 等）会自动解决，程序落在 /opt/folia-major：
yay -S folia-major-bin
用 paru 的话把命令里的 yay 换成 paru。要留意：PKGBUILD 里固定的版本号可能落后于 Releases 最新发布，装完核对一下，清单在 packaging/aur/folia-major-bin/PKGBUILD。
⚠️ Linux 启动后黑屏、透明度异常或闪退，多半是显卡兼容问题，不是装坏了。先用软件渲染启动一次验证，命令作用是强制走软件渲染、绕开显卡驱动：
FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major
还不稳定就改用 software 值，确认没事后用 system 恢复系统图形路径。Wayland/Hyprland 等桌面环境的更多细节在 docs/technical.md。
怎么判断装成功了：勾选这 3 个信号
- 版本对得上：打开「设置 → 帮助」，把显示的版本号和你下载文件名里的版本号比一下，一致才算装对；对不上说明拿错了包或镜像没同步，回 Releases 重新下，别将就旧版。
- 能放出声音：登录任一个在线音源，或导入一个本地音频文件夹，随便点一首歌能正常播放。
- 全屏歌词亮起来：点一首有歌词的歌，全屏歌词动画会自动出现——这一步做到了，才叫真正装完。再进设置换两三个主题试试，每个主题的排版氛围差很多。
不想装桌面版？
桌面版之外还有 Web 形态：可自托管部署（NAS、服务器都行，见 deploy/docker/README.md 的 Docker Compose 全栈部署），部署后在手机浏览器「添加到主屏幕」即可当 PWA 用。这条路线要跑命令行、配环境变量，想试的从部署文档入手即可。
装完的下一步
回到开头的三问确认你拿对了包，走完对应平台的坑点，勾满「成功信号清单」里的三项，全屏歌词亮起来才算真正收尾。之后想接本地曲库、换主题或部署 Web 版，按上面各节的链接继续深入就行。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
