Folia 全屏歌词播放器安装部署实录：桌面 + Web 全平台 3 条路径一次跑通

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器 A multi-platform music player for local files, Navidrome, and online streaming services, featuring stunning animated lyrics.项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major

Folia 是把歌词渲染成全屏动画、可接网易云/酷狗/QQ 音乐/Navidrome/本地库的播放器。本篇按「预检 → 最短路径 → 其他场景 → 验收」走一遍安装部署，读完后你能在任意一台机器上挑对路径并把它跑起来。

一、动手前先过这张表

💡 最容易踩的坑：网盘镜像只放Windows.exe与 Apple silicon.dmg两个包，Intel Mac 和所有 Linux 发行版都不在其中，一律走 Releases。

二、最短路径 —— 官方桌面包 3 步装好

桌面版内置前后端运行环境，即装即用，是最快的路径。

1. 打开仓库 README.md 的「快速下载」一节取包：国内网络用夸克/百度网盘（百度提取码flia），能打开 Releases 页的直接去 Releases 页取对应平台最新版本。

   选包只认两条依据：平台（.exe/.dmg/.deb/.rpm/linux-x64.tar.gz）和芯片（arm64 / x64）。

2. 对一眼网盘里的版本号与最新 release，确认没有明显滞后；确认无误后双击安装器按提示走完（macOS 用户把Folia.app拖进 Applications，别在挂载盘里直接跑）。
3. 从应用菜单启动 Folia，跳过首启的两道引导弹窗（思索模式、资料库界面选择）。

✅ 此时你应该能看到首页的 Playlists / Radio / Albums / Folder 标签页和搜索框，搜到第一首歌并正常播放。

三、其他环境 / 场景部署

macOS（全芯片）：Releases 取 dmg，一步清除 Gatekeeper 拦截

适用：所有 Mac 用户。当前发布的 macOS 版没有 Apple Developer ID 签名与公证，首启被拦截是正常现象，不是包坏了。

1. 到 Releases 页面下载当前版本、对应芯片（arm64 / x64）的 dmg。
2. 挂载 dmg，把Folia.app拖进 Applications。
3. 弹出「应用已损坏」或「无法验证」时，在终端执行：

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

4. 从 Applications 重新打开应用。

macOS 版不支持应用内自动更新，每次手动重装覆盖后都会重新带上隔离属性，需要再执行一遍上面的 xattr 命令。完整排错见 docs/desktop/macos-app-damaged.md。

Arch / Manjaro：AUR 一条命令

适用：已装好 yay 或 paru 的 Arch 系用户。

yay --version # 确认 AUR 助手可用 yay -S folia-major-bin # 构建时拉 Releases 的 linux-x64 包装进 /opt/folia-major command -v folia-major # 应输出 /usr/bin/folia-major

然后从应用菜单启动即可。

AUR 包当前版本 0.1.4，明显落后主仓库的 0.7.25（见package.json），依赖 alsa-lib、gtk3、libxss、nss，可对照 packaging/aur/folia-major-bin/PKGBUILD 逐项核对。构建本质就是一次下载，卡住别干等，直接转下面的便携包路线。

Debian / Ubuntu / Fedora 等发行版：linux-x64 便携包手动部署

适用：非 Arch 系发行版，或想把程序收进一个便携目录的用户。

1. 到 Releases 页面按发行版取包：Debian / Ubuntu / Mint 取.deb，Fedora / RHEL / openSUSE 取.rpm，其他发行版取形如folia-major-<version>-linux-x64.tar.gz的便携包。
2. （仅 tar.gz 用户）解压到固定目录：

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

3. 把便携包自带的桌面项模板复制到用户级应用目录：

cp ~/Apps/Folia/resources/linux/folia-major.desktop ~/.local/share/applications/ # 安装桌面项模板

4. 打开这个.desktop文件，把__APP_PATH__换成folia-major可执行文件的绝对路径、__ICON_PATH__换成resources/linux/icon.png的绝对路径。
5. 桌面环境有要求时把该文件标记为可信，然后从应用菜单启动 Folia。

便携包一共三样东西：folia-major可执行文件、resources/linux/icon.png和桌面项模板。排查问题时先确认可执行文件与resources/目录位于同一便携包内。

服务器 / NAS：Docker Compose 自托管 Web 版

适用：不想装 PC、要用浏览器打开 Folia 的用户。要求 Docker Engine 24+ 与 Compose v2。

1. 建一个空部署目录，把仓库的deploy/docker/compose.yaml和deploy/docker/.env.example取到同一目录，后者改名为.env（字段说明见 deploy/docker/README.md）。
2. 生成随机串填进.env的SYNC_TOKEN：

openssl rand -hex 32 # 生成 SYNC_TOKEN 用的随机字符串，至少八位

3. 校验并启动全栈：

docker compose config # 校验 compose 与环境变量 docker compose up -d --wait # 拉取镜像并启动全部服务，等待健康检查通过 docker compose ps # 确认各服务状态

4. 浏览器打开http://<服务器IP>:18080进入 Folia 首页。

对外只发布 Web 网关 18080 与 Sync Server 13000 两个端口；AI 配置留空不影响音乐播放。本地音乐目录访问依赖可信 HTTPS 安全上下文，部署到 NAS 时先读deploy/docker/README.md里的反向代理与证书要求。

四、跑通确认

Linux 启动后若黑屏、透明度/模糊异常或 GPU 崩溃，通常是图形路径问题而不是装坏了，加环境变量强制软件渲染：

FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major # 以 swiftshader 软件渲染方式启动 FOLIA_LINUX_GRAPHICS_MODE=software ./folia-major # 仍不稳定时用最保守的软件渲染档位

表里三项都过了，就算装好了，可以放心开始调歌词动画主题。

五、卡住了？按现象查

六、相关文档

• packaging/linux/README-LINUX.txt：FOLIA_LINUX_GRAPHICS_MODE/FOLIA_LINUX_VULKAN图形变量说明与壁纸模式细节。
• docs/desktop/macos-app-damaged.md：Gatekeeper「应用已损坏」的完整排错流程，含两种放行方案。
• deploy/docker/README.md：Docker Compose 全栈的端口、环境变量表、Navidrome 预置账号与 NAS 反向代理要求。

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器 A multi-platform music player for local files, Navidrome, and online streaming services, featuring stunning animated lyrics.项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major