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-majorFolia 是一款全屏歌词动画音乐播放器接得动网易云、酷狗、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 自托管三条安装路线路线一官方安装包一键装好桌面版适用对象想在个人电脑上即装即用的用户。选包Windows 取.exe安装器macOS 取.dmg按芯片选 arm64 或 x64。国内网络可按 README「快速下载」一节取夸克 / 百度网盘链接百度提取码flia其余平台去项目 Releases 页面下载。安装Windows 双击安装器按提示走完macOS 挂载 dmg 后把Folia.app拖进 Applications不要直接在挂载盘里运行。macOS 若弹出「应用已损坏」或「无法验证」在终端执行xattr -dr com.apple.quarantine /Applications/Folia.app # 移除下载隔离属性Gatekeeper 不再拦截从开始菜单Windows、ApplicationsmacOS或应用菜单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.25package.json想拿最新版请继续走本路线的 tar.gz。到 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和桌面项模板见 packaging/linux/README-LINUX.txt。排查问题时先确认可执行文件与resources/位于同一便携包目录内。路线三用 Docker Compose 把 Folia Web 版跑起来适用对象想在 NAS / 服务器上用浏览器打开 Folia、不想装 PC 的用户。新建一个空目录把deploy/docker/compose.yaml和deploy/docker/.env.example放进该目录后者改名为.env。生成随机串填进.env的SYNC_TOKENopenssl rand -hex 32 # 生成 SYNC_TOKEN 用的随机字符串校验配置然后拉镜像并启动等待健康检查通过docker compose up -d --wait # 拉取镜像并启动全部服务等待健康检查通过浏览器打开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_MODEswiftshader ./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_MODEswiftshader强制软件渲染再启动仍不稳定就改用FOLIA_LINUX_GRAPHICS_MODEsoftware最保守档位。这是图形路径问题不是装坏了。桌面快捷方式不显示或图标是空的先检查.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 --tail200看日志拉不动镜像先检查网络FOLIA_IMAGE_NAMESPACE缺失时 Compose 会拒绝启动。进阶资料packaging/linux/README-LINUX.txtFOLIA_LINUX_GRAPHICS_MODE/FOLIA_LINUX_VULKAN图形变量说明与壁纸模式wlr-layer-shell细节Linux 图形问题都从这里查。docs/technical.mdRealeco / Limo / Cielo 三条更新通道、.deb/.rpm等获取方式以及开发与环境变量说明。deploy/docker/README.mdDocker 全栈的端口、环境变量、QQ 音乐与 Navidrome 预置账号配置、NAS 反向代理与证书要求。docs/local-library-management.md本地音乐库的导入、重扫、在线匹配与歌单管理曲库对不上号时看它。docs/folium/api.mdFolium 模组 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），仅供参考