尧图网站建设 免费方案咨询
ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

首页/资讯中心/资讯详情

Folia 完整安装指南：桌面与 NAS 一次跑通全屏歌词动画播放器

发布时间：2026/11/5 1:47:50 尧图网站建设
Folia 完整安装指南：桌面与 NAS 一次跑通全屏歌词动画播放器

Folia 完整安装指南：桌面与 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

Folia 是一款全屏歌词动画音乐播放器，接得动网易云、酷狗、QQ 音乐、Navidrome 和本地音乐库，提供桌面版（Windows / macOS / Linux）与自托管 Web 版。本文按「选渠道 → 安装 → 验收」三条路线带你跑完，十分钟上手。

动手前：30 秒自检

先对照清单确认你的环境走得通：

  • 🎯 桌面版：无需额外安装依赖，官方安装包内置前后端运行环境，Windows / macOS / Linux 普通电脑即可
  • Linux 便携版：有图形桌面环境（X11 或 Wayland）即可，不需要编译器
  • Docker 版：要求 Docker Engine 24+ 与 Docker Compose v2
  • 网络：在线音乐需要稳定外网；本地音乐库可离线用；Docker 需要能拉取镜像
  • Node.js ≥ 24 仅「从源码运行 / 参与开发」时需要，正常安装使用用不到

你是谁，走哪条路线：

你是谁走哪条路线
个人电脑，装完就想用路线一：官方安装包一键装
非 Arch 系 Linux，或想把程序收进便携目录路线二：便携版手动部署
NAS / 服务器，想浏览器里打开路线三：Docker Compose 自托管

三条安装路线

路线一：官方安装包一键装好桌面版

适用对象：想在个人电脑上即装即用的用户。

  1. 选包：Windows 取.exe安装器，macOS 取.dmg（按芯片选 arm64 或 x64）。国内网络可按 README「快速下载」一节取夸克 / 百度网盘链接（百度提取码flia），其余平台去项目 Releases 页面下载。
  2. 安装：Windows 双击安装器按提示走完；macOS 挂载 dmg 后把Folia.app拖进 Applications，不要直接在挂载盘里运行。
  3. macOS 若弹出「应用已损坏」或「无法验证」，在终端执行：
xattr -dr com.apple.quarantine /Applications/Folia.app # 移除下载隔离属性，Gatekeeper 不再拦截
  1. 从开始菜单（Windows）、Applications（macOS）或应用菜单（Linux）启动 Folia。

⚠️ 网盘只有 Windows 与 Apple silicon 两个包，Intel Mac 和所有 Linux 发行版都要去 Releases 页面取对应平台安装包。macOS 版目前没有 Apple Developer ID 签名与公证，每次手动重装后都要再执行一遍上面的 xattr 命令。

路线二：解压 Linux 便携版到固定目录并建好桌面快捷方式

适用对象：非 Arch 系发行版的 Linux 用户，或想把程序收进一个便携目录的人。Arch / Manjaro 用户可以直接yay -S folia-major-bin，但 AUR 包当前是 0.1.4，落后主仓库的 0.7.25（package.json），想拿最新版请继续走本路线的 tar.gz。

  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和桌面项模板，见 packaging/linux/README-LINUX.txt。排查问题时先确认可执行文件与resources/位于同一便携包目录内。

路线三：用 Docker Compose 把 Folia Web 版跑起来

适用对象：想在 NAS / 服务器上用浏览器打开 Folia、不想装 PC 的用户。

  1. 新建一个空目录，把deploy/docker/compose.yaml和deploy/docker/.env.example放进该目录，后者改名为.env。
  2. 生成随机串填进.env的SYNC_TOKEN：
openssl rand -hex 32 # 生成 SYNC_TOKEN 用的随机字符串
  1. 校验配置，然后拉镜像并启动，等待健康检查通过：
docker compose up -d --wait # 拉取镜像并启动全部服务，等待健康检查通过
  1. 浏览器打开http://<服务器IP>:18080进入 Folia 首页。

⚠️ 对外只发布 Web 网关 18080 与 Sync Server 13000 两个端口，AI 配置留空不影响音乐播放。要用「本地音乐目录」能力必须处于可信 HTTPS 安全上下文，NAS 部署需要反向代理终结证书，要求见 deploy/docker/README.md。

首次启动与验收

首次启动会依次弹出几个引导弹窗（版本说明、播放入口视图选择等），一路跳过即可。满足下面三条就算装好了：

  • ✅ Folia 出现在应用菜单里（Windows 看开始菜单、macOS 看 Applications、Linux 看应用菜单）
  • ✅ 首页能看到 Playlists / Radio / Albums / Folder 标签页和搜索框
  • ✅ 能搜到歌曲并正常播放，全屏歌词动画正常出现

首启常见坑各一句带过：macOS 弹「应用已损坏」就重跑一遍 xattr 命令；Linux 黑屏、透明度 / 模糊异常或 GPU 崩溃，先试：

FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major # 以 swiftshader 软件渲染方式启动

Web 版「本地音乐目录」不可用，多半是局域网 IP 的普通 HTTP 不属于浏览器安全上下文，加反向代理上 HTTPS 即可。

卡住了？对照这些情况

网盘里没有自己平台的包？先去项目 Releases 页面取对应平台的安装包；仍找不到就翻 README「获取方式」一节，AUR、Flatpak、PWA 等渠道都有列。

macOS 提示「应用已损坏」打不开？先执行xattr -dr com.apple.quarantine /Applications/Folia.app，再从 Applications 重新打开。还不行就删除Folia.app和 dmg，从 Releases 重新下载后再执行一次；完整排错见 docs/desktop/macos-app-damaged.md。

Linux 黑屏、透明度 / 模糊异常或 GPU 崩溃？先加FOLIA_LINUX_GRAPHICS_MODE=swiftshader强制软件渲染再启动；仍不稳定就改用FOLIA_LINUX_GRAPHICS_MODE=software最保守档位。这是图形路径问题，不是装坏了。

桌面快捷方式不显示，或图标是空的？先检查.desktop文件里Exec/Icon是否还是__APP_PATH__/__ICON_PATH__占位符、有没有换成绝对路径；再确认桌面环境是否要求把文件标记为可信。

Web 版导入不了本地音乐目录？这是 File System Access API 依赖可信 HTTPS 安全上下文导致的。先确认浏览器是桌面版 Chromium 系；仍不行就让 NAS 反向代理指向 18080 终结 HTTPS，证书链必须被浏览器信任。

docker compose up卡住或有服务不健康？先docker compose ps看哪个容器没起来，再用docker compose logs --tail=200看日志；拉不动镜像先检查网络，FOLIA_IMAGE_NAMESPACE缺失时 Compose 会拒绝启动。

进阶资料

  • packaging/linux/README-LINUX.txt：FOLIA_LINUX_GRAPHICS_MODE/FOLIA_LINUX_VULKAN图形变量说明与壁纸模式（wlr-layer-shell）细节，Linux 图形问题都从这里查。
  • docs/technical.md：Realeco / Limo / Cielo 三条更新通道、.deb/.rpm等获取方式，以及开发与环境变量说明。
  • deploy/docker/README.md：Docker 全栈的端口、环境变量、QQ 音乐与 Navidrome 预置账号配置、NAS 反向代理与证书要求。
  • docs/local-library-management.md：本地音乐库的导入、重扫、在线匹配与歌单管理，曲库对不上号时看它。
  • docs/folium/api.md：Folium 模组 API 参考，想给自己的歌词动画写模组从这里入手。

【免费下载链接】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），仅供参考

网站建设 视觉设计 SEO优化
返回列表