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

发布时间：2026/11/5 5:16:46
Folia 全屏歌词播放器安装部署实录：桌面 + Web 全平台 3 条路径一次跑通

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/本地库的播放器。本篇按「预检 → 最短路径 → 其他场景 → 验收」走一遍安装部署，读完后你能在任意一台机器上挑对路径并把它跑起来。

一、动手前先过这张表

检查项判断标准不满足时的替代路径
Docker 版本（Web 自托管）Docker Engine 24+ 与 Compose v2低于 24 先升级 Docker；升不了就走桌面安装包
AUR 助手（Arch 路线）yay --version能正常输出换 linux-x64 便携包手动部署
Mac 芯片架构Apple silicon 还是 IntelIntel 不在网盘镜像里，只能去 Releases 页
国内网络README「快速下载」的网盘链接可打开、版本未明显滞后链接失效或版本落后时，直接去项目 Releases 页取包

💡 最容易踩的坑：网盘镜像只放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 不再拦截
  1. 从 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 # 整套程序放进固定目录
  1. 把便携包自带的桌面项模板复制到用户级应用目录：
cp ~/Apps/Folia/resources/linux/folia-major.desktop ~/.local/share/applications/ # 安装桌面项模板
  1. 打开这个.desktop文件，把__APP_PATH__换成folia-major可执行文件的绝对路径、__ICON_PATH__换成resources/linux/icon.png的绝对路径。
  2. 桌面环境有要求时把该文件标记为可信，然后从应用菜单启动 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 用的随机字符串，至少八位
  1. 校验并启动全栈：
docker compose config # 校验 compose 与环境变量 docker compose up -d --wait # 拉取镜像并启动全部服务，等待健康检查通过 docker compose ps # 确认各服务状态
  1. 浏览器打开http://<服务器IP>:18080进入 Folia 首页。

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

四、跑通确认

现象判定
桌面版出现在应用菜单并能打开；Web 版http://<IP>:18080显示 Folia 首页启动成功
搜索歌曲后正常播放，歌词带动画铺满全屏，封面与主题自动加载核心功能可交互
docker compose ps全绿、docker compose logs无持续报错输出无报错日志

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

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

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

五、卡住了？按现象查

现象最可能原因第一步动作跳转锚点
macOS 提示「应用已损坏」「无法验证」未签名/未公证版被 Gatekeeper 拦截重装后重新执行 xattr 命令macOS 路线
AUR 构建卡在下载步骤网络拉不动 Releases 包放弃 AUR，改走便携 tar.gz 部署便携包路线
Linux 黑屏、GPU 崩溃系统图形路径不兼容加FOLIA_LINUX_GRAPHICS_MODE=swiftshader启动跑通确认
桌面快捷方式不显示.desktop里还是__APP_PATH__占位符或未标记可信确认 Exec / Icon 是绝对路径、文件已标记可信便携包路线
Web 版能打开但本地目录导入不可用局域网 IP 的普通 HTTP 不是浏览器安全上下文按文档配 HTTPS 反向代理Docker 自托管路线
浏览器打不开 Web 首页SYNC_TOKEN未填或端口被占检查.env，跑docker compose ps与docker compose logsDocker 自托管路线

六、相关文档

  • 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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考