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-majorFolia 是把歌词渲染成全屏动画、可接网易云/酷狗/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 步装好桌面版内置前后端运行环境即装即用是最快的路径。打开仓库 README.md 的「快速下载」一节取包国内网络用夸克/百度网盘百度提取码flia能打开 Releases 页的直接去 Releases 页取对应平台最新版本。选包只认两条依据平台.exe/.dmg/.deb/.rpm/linux-x64.tar.gz和芯片arm64 / x64。对一眼网盘里的版本号与最新 release确认没有明显滞后确认无误后双击安装器按提示走完macOS 用户把Folia.app拖进 Applications别在挂载盘里直接跑。从应用菜单启动 Folia跳过首启的两道引导弹窗思索模式、资料库界面选择。✅ 此时你应该能看到首页的 Playlists / Radio / Albums / Folder 标签页和搜索框搜到第一首歌并正常播放。三、其他环境 / 场景部署macOS全芯片Releases 取 dmg一步清除 Gatekeeper 拦截适用所有 Mac 用户。当前发布的 macOS 版没有 Apple Developer ID 签名与公证首启被拦截是正常现象不是包坏了。到 Releases 页面下载当前版本、对应芯片arm64 / x64的 dmg。挂载 dmg把Folia.app拖进 Applications。弹出「应用已损坏」或「无法验证」时在终端执行xattr -dr com.apple.quarantine /Applications/Folia.app # 移除下载隔离属性Gatekeeper 不再拦截从 Applications 重新打开应用。macOS 版不支持应用内自动更新每次手动重装覆盖后都会重新带上隔离属性需要再执行一遍上面的 xattr 命令。完整排错见 docs/desktop/macos-app-damaged.md。Arch / ManjaroAUR 一条命令适用已装好 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 系发行版或想把程序收进一个便携目录的用户。到 Releases 页面按发行版取包Debian / Ubuntu / Mint 取.debFedora / RHEL / openSUSE 取.rpm其他发行版取形如folia-major-version-linux-x64.tar.gz的便携包。仅 tar.gz 用户解压到固定目录mkdir -p ~/Apps/Folia tar -xzf folia-major-*-linux-x64.tar.gz -C ~/Apps/Folia # 整套程序放进固定目录把便携包自带的桌面项模板复制到用户级应用目录cp ~/Apps/Folia/resources/linux/folia-major.desktop ~/.local/share/applications/ # 安装桌面项模板打开这个.desktop文件把__APP_PATH__换成folia-major可执行文件的绝对路径、__ICON_PATH__换成resources/linux/icon.png的绝对路径。桌面环境有要求时把该文件标记为可信然后从应用菜单启动 Folia。便携包一共三样东西folia-major可执行文件、resources/linux/icon.png和桌面项模板。排查问题时先确认可执行文件与resources/目录位于同一便携包内。服务器 / NASDocker Compose 自托管 Web 版适用不想装 PC、要用浏览器打开 Folia 的用户。要求 Docker Engine 24 与 Compose v2。建一个空部署目录把仓库的deploy/docker/compose.yaml和deploy/docker/.env.example取到同一目录后者改名为.env字段说明见 deploy/docker/README.md。生成随机串填进.env的SYNC_TOKENopenssl rand -hex 32 # 生成 SYNC_TOKEN 用的随机字符串至少八位校验并启动全栈docker compose config # 校验 compose 与环境变量 docker compose up -d --wait # 拉取镜像并启动全部服务等待健康检查通过 docker compose ps # 确认各服务状态浏览器打开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_MODEswiftshader ./folia-major # 以 swiftshader 软件渲染方式启动 FOLIA_LINUX_GRAPHICS_MODEsoftware ./folia-major # 仍不稳定时用最保守的软件渲染档位表里三项都过了就算装好了可以放心开始调歌词动画主题。五、卡住了按现象查现象最可能原因第一步动作跳转锚点macOS 提示「应用已损坏」「无法验证」未签名/未公证版被 Gatekeeper 拦截重装后重新执行 xattr 命令macOS 路线AUR 构建卡在下载步骤网络拉不动 Releases 包放弃 AUR改走便携 tar.gz 部署便携包路线Linux 黑屏、GPU 崩溃系统图形路径不兼容加FOLIA_LINUX_GRAPHICS_MODEswiftshader启动跑通确认桌面快捷方式不显示.desktop里还是__APP_PATH__占位符或未标记可信确认 Exec / Icon 是绝对路径、文件已标记可信便携包路线Web 版能打开但本地目录导入不可用局域网 IP 的普通 HTTP 不是浏览器安全上下文按文档配 HTTPS 反向代理Docker 自托管路线浏览器打不开 Web 首页SYNC_TOKEN未填或端口被占检查.env跑docker compose ps与docker compose logsDocker 自托管路线六、相关文档packaging/linux/README-LINUX.txtFOLIA_LINUX_GRAPHICS_MODE/FOLIA_LINUX_VULKAN图形变量说明与壁纸模式细节。docs/desktop/macos-app-damaged.mdGatekeeper「应用已损坏」的完整排错流程含两种放行方案。deploy/docker/README.mdDocker 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），仅供参考