Folia 安装指南：在 Windows / macOS / Linux 上跑起全屏歌词播放器

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

Folia 是一个全屏沉浸式歌词音乐播放器，把歌词做成铺满整个屏幕的动画，支持网易云、QQ 音乐、酷狗在线音源，也能接入 Navidrome 和本地音乐库。本文覆盖 Windows、macOS、Linux 三个桌面平台的安装过程。桌面版把前后端运行环境都打进了安装包，不需要 Node.js 和任何开发工具，跟着走一遍就能放起歌来。

先对号入座：选对环境与安装包

网盘镜像只覆盖 Windows 与 Apple silicon 的正式版，Intel Mac 和所有 Linux 包都要从 Releases 页直接下。文件名都带平台和架构标识，下载前逐字比对一次。

分平台安装步骤

Windows 安装

从 Releases 页或网盘镜像下载 .exe。下完先核对文件名里的版本号，和 Releases 页最新标注一致才算数，对不上就等镜像同步或改走 Releases 重下。双击安装包，向导走到底即可。开始菜单或桌面出现 Folia 图标，点开能看到主界面，装到位了。

macOS 安装

打开 .dmg，把 Folia 拖进 Applications 文件夹。注意不要直接在挂载盘窗口里运行。首次启动如果弹出「Folia.app 已损坏」或「无法验证」，不是包坏了：官方版本目前没有 Apple Developer ID 签名，macOS 拦截的是下载隔离属性。在终端执行下面这条命令，再从 Applications 重新打开：

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

macOS 版暂不支持应用内自动更新，每次覆盖安装新版本后都要再跑一次这条命令，完整说明见 docs/desktop/macos-app-damaged.md。启动台里能看到 Folia 图标且能打开主界面，就对了。

Linux 安装

Debian / Ubuntu / Mint 下 .deb，Fedora / RHEL / openSUSE 下 .rpm，其他发行版用 .tar.gz，全部从 Releases 页获取。tar.gz 解压到任意目录，直接运行里面的folia-major可执行文件。压缩包自带图标和.desktop模板，想建桌面启动项的话，把模板复制到~/.local/share/applications/，再把__APP_PATH__、__ICON_PATH__两个占位符换成实际绝对路径，按桌面环境要求标记可信，细节见 packaging/linux/README-LINUX.txt。应用菜单里出现 Folia 且能点开主界面，安装完成。

首次启动后验证这四项

• ✅ 版本：「关于」页版本号和安装包文件名里的版本一致
• ✅ 音源：成功登录一个在线音源，或导入本地文件夹、接入 Navidrome
• ✅ 歌词：播一首带歌词的歌，全屏歌词动画正常亮起
• ✅ 主题：切换两三个歌词主题，排版氛围切换无异常

替代与进阶路线

AUR 一键安装（Arch）

Arch / Manjaro 用户不用手动下包：

yay -S folia-major-bin

paru 用户把yay换成paru。程序装到/opt/folia-major，依赖项和安装逻辑都在 packaging/aur/folia-major-bin/PKGBUILD 里。构建阶段拉压缩包慢的话，可以先用网盘下好同版本 tar.gz 放进 AUR 源码目录，再执行makepkg -si。

Docker 部署 Web 版（NAS / 浏览器）

不装桌面端，可以把 Web 版本部署到 NAS 或服务器。完整堆栈的 Compose 文件在 deploy/docker/，要求 Docker Engine 24+ 与 Compose v2，启动后默认访问http://NAS-IP:18080。环境变量、Navidrome 预置账号等配置见 deploy/docker/README.md。

手机 PWA

Web 版部署好后，在 Chrome for Android 或 iOS Safari 里把页面添加到主屏幕，手机上就能当 App 用，适合移动端场景。

问题速查

下载总断流→ 多为国内网络直连 GitHub Releases 太慢 → 换官方网盘镜像（夸克、百度），取回后再核对一遍版本号。

Linux 启动黑屏或闪退→ 多半是 GPU 兼容问题 → 用FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major以软件渲染验证；仍不稳定切software；确认是显卡问题后再用system恢复系统路径。

macOS 提示应用已损坏→ 未签名应用带下载隔离属性被 Gatekeeper 拦截 → 执行xattr -dr com.apple.quarantine /Applications/Folia.app后重新打开。

拿错了包→ Intel Mac 装了 Apple silicon 版，或 Linux 架构不匹配 → 回 Releases 页逐字比对文件名再重新下载。

挑一首带歌词的歌，让整屏亮起来。

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