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 是一个 Electron 桌面 + Node.js Web 的歌词动画播放器，把歌词渲染成全屏动画，接得动网易云、酷狗、QQ 音乐、Navidrome 与本地音乐库，覆盖 Windows / macOS / Linux 桌面与 Docker 自托管 Web 三种形态。本文按「预检 → 选路 → 安装 → 验收」走完全流程，读完能选对路线并装好。
动手前 30 秒预检：确认平台、版本与网络
装之前先回答三个问题，避免装到一半发现走错路：
- 平台与芯片：Windows x64、Apple silicon、Intel Mac、Linux 发行版。芯片决定你下载哪个 macOS 包。
- 网络：能否直接打开项目 Releases 页面？不能的话，国内网络走 README「快速下载」一节的网盘镜像（百度提取码
flia）——但网盘只有 Windows.exe与 Apple silicon.dmg两个包，其余平台一律回 Releases 页面取。 - 服务器用户：确认 Docker Engine 24+ 与 Compose v2：
docker --version # 确认 Docker 与 Compose 版本达标你该走哪条路：三个问题的判定逻辑
- 问题一：装在自己电脑上，还是装到服务器 / NAS 上？自己的电脑走桌面版；服务器、NAS、想浏览器访问走 Docker 全栈。
- 问题二（桌面版）：什么系统？Windows / macOS 直接装 Releases 的安装包；Arch / Manjaro 走 AUR；其他 Linux 发行版用
.deb/.rpm/ 便携 tar 包。 - 问题三：要不要跨设备同步主题？可选。Docker 全栈自带 Sync Server（端口 13000），桌面版在「设置 → 连接与集成」填服务端地址和
SYNC_TOKEN即可接入。
判定完毕，往下对应小节照做。
桌面版安装：Windows、macOS、Linux 三条路线
Windows 安装 .exe
- 打开项目 Releases 页面，下载最新版 Windows 安装包
.exe；国内网络可改用 README「快速下载」的网盘链接，内容与 Releases 同源。 - 双击运行安装器，按提示走完默认流程，目的是把程序装入系统并生成开始菜单快捷方式。
- 在开始菜单搜索 Folia 并启动。
macOS 处理 Gatekeeper 拦截
- 到 Releases 页面按芯片取包：Apple silicon 选 arm64，Intel 选 x64。
- 挂载 dmg，把
Folia.app拖进 Applications——不要直接在挂载盘里运行。 - 首启弹「应用已损坏」或「无法验证」时，属预期现象：当前发布没有 Apple Developer ID 签名与公证。在终端执行：
xattr -dr com.apple.quarantine /Applications/Folia.app # 移除下载隔离属性，Gatekeeper 不再拦截- 从 Applications 重新打开。
⚠️ macOS 版没有应用内自动更新。每次用新版本覆盖安装后，都要重新执行一遍上面的 xattr 命令。完整排错见 docs/desktop/macos-app-damaged.md。
Arch Linux 走 AUR 一条命令
yay -S folia-major-bin # 从 AUR 构建，拉取 Releases 的 linux-x64 包装进 /opt/folia-major command -v folia-major # 确认软链接挂在 /usr/bin 下包会在应用菜单生成 Folia 入口，依赖 alsa-lib、gtk3、libxss、nss，可对照 packaging/aur/folia-major-bin/PKGBUILD 逐项核对。注意：AUR 包当前停留在 0.1.4，而主仓库package.json已是 0.7.25，版本差很远。想要最新版就跳过 AUR，直接走下面的便携版。
其他 Linux 发行版部署便携版
- 按发行版取包：Debian / Ubuntu / Mint 取
.deb，Fedora / 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 的绝对路径，模板原文见 packaging/linux/folia-major.desktop。 - 桌面环境有要求时把文件标记为可信，然后从应用菜单启动。
💡 便携包一共三样东西：folia-major可执行文件、resources/linux/icon.png和桌面项模板。排查问题时先确认可执行文件与resources/在同一便携包目录内，详见 packaging/linux/README-LINUX.txt。
Docker Compose 自托管：把 Web 版跑在服务器或 NAS 上
桌面装不了、或想浏览器访问的用户走这条线。
准备 compose.yaml 与 .env
新建空目录，从仓库deploy/docker/取compose.yaml和.env.example两个文件放进去，后者改名为.env。字段含义逐项写在 deploy/docker/README.md 里，不需要预下载源码。
生成并填入 SYNC_TOKEN
openssl rand -hex 32 # 生成 Sync Server 的 Bearer Token 随机串把输出填入.env的SYNC_TOKEN（至少八位，必填）。FOLIA_IMAGE_NAMESPACE、FOLIA_HTTP_PORT等有默认值；AI 密钥留空不影响播放。
启动全栈并验证
docker compose up -d --wait # 拉取镜像、启动全部服务，等待健康检查通过 docker compose ps # 查看各容器状态，应全部 healthy / running浏览器打开http://<服务器IP>:18080进首页；http://<服务器IP>:13000/health是 Sync Server 健康检查入口。对外只发布 18080 与 13000 两个端口，网易云、酷狗、QQ 接口都在 Docker 内部网络，不直接暴露。
⚠️ 局域网 IP 上的普通 HTTP 不属于浏览器安全上下文，本地音乐目录导入等功能会不可用。部署到 NAS 时先按 deploy/docker/README.md 配好反向代理与 HTTPS 证书。有 Navidrome 的话，在.env填NAVIDROME_URL/NAVIDROME_USERNAME/NAVIDROME_PASSWORD三项，新打开的浏览器会自动登录。
Linux 启动异常：先用软件渲染试一次
桌面版在 Linux 上黑屏、透明度 / 模糊异常或 GPU 崩溃，通常是图形路径问题而不是装坏了。加环境变量强制软件渲染：
FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major # 以 swiftshader 软件渲染方式启动 FOLIA_LINUX_GRAPHICS_MODE=software ./folia-major # 仍不稳定时用最保守的软件渲染档位恢复正常后改回FOLIA_LINUX_GRAPHICS_MODE=system。X11 下 WebGPU 不可用的场景可用FOLIA_LINUX_VULKAN=1 ./folia-major --ozone-platform=x11手动开 Vulkan，完整变量说明见 packaging/linux/README-LINUX.txt。
装完你得到什么：验收标准
Folia 出现在应用菜单（Windows 看开始菜单、macOS 看 Applications、Linux 看应用菜单），点开后跳过首启的两道引导弹窗，首页出现 Playlists / Radio / Albums / Folder 标签页和搜索框，能进入第一首歌、全屏歌词动画正常渲染——看到这些状态就算装好了 ✅。Web 版则确认http://<服务器IP>:18080打开同一套首页。
【免费下载链接】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），仅供参考
