Folia 歌词动画播放器完整安装指南：桌面端、Docker 与自托管 Web 一次跑通-开发者社区

Folia 歌词动画播放器完整安装指南：桌面端、Docker 与自托管 Web 一次跑通

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major

Folia 是一个把歌词渲染成全屏动画的音乐播放器，支持网易云、QQ 音乐、酷狗、Navidrome 和本地音乐库。本文只解决一件事：怎么把 Folia 装到 Windows、macOS、Linux 上并跑起来，再在 NAS 或服务器上部署 Web 版，出问题时往哪查。当前版本以 package.json 的0.7.23为准。

开装前 30 秒：对号入座表

先按下表定位自己的路线，能省掉一半试错时间：

你的环境	推荐路线	最容易踩的坑
Windows	Releases 的`.exe`安装包	下载慢，需转 README「快速下载」的网盘镜像
macOS	Releases 的`.dmg`（按芯片选架构）	首次打开弹「应用已损坏」，需一条命令放行
Arch / Manjaro	AUR 包`folia-major-bin`	构建时去 Releases 拉包，下载慢会长时间卡住
Debian / Fedora / 其他	`.deb`/`.rpm`或`linux-x64`的 tar.gz	便携版装完没有菜单项，要手动补桌面项
NAS / 自有服务器	Docker Compose 全栈	`SYNC_TOKEN`不填或太短，栈直接拒绝启动
手机 / 浏览器	先部署 Web 版，再把网页加入主屏幕	局域网 HTTP 下本地音乐目录导入不可用，需 HTTPS

Windows 与 macOS：装完还差一条命令

Windows：Releases 页面取最新的Folia-Setup-0.7.23.exe，双击按向导走完即可。桌面版内置前后端运行环境，装完即用，不需要 Node.js，不依赖任何额外运行时。下载慢到掉线别干等：README.md「快速下载」一节挂了夸克网盘和百度镜像（提取码flia），注意网盘只有 Windows 和 Apple silicon 两个正式版安装包，取下来先对一眼版本号再装。

macOS：Releases 取.dmg，Apple silicon 选arm64、Intel 选x64，把Folia.app拖进Applications再启动。国内首次打开基本都会遇到「应用已损坏」弹窗——不是包坏了，而是当前发布没有 Apple Developer ID 签名，浏览器下载又打了隔离标记，Gatekeeper 把签名不完整的应用显示成「已损坏」。装完执行：

xattr -dr com.apple.quarantine /Applications/Folia.app # 移除下载隔离标记

然后从Applications重新打开。macOS 版暂不支持应用内自动更新，每次覆盖安装新版后这条命令要再跑一次。提示的是「无法验证」而不是「已损坏」（常见于 Intel Mac），改走系统设置 → 隐私与安全性 → 「仍要打开」。详细分支见 docs/desktop/macos-app-damaged.md。

Linux：AUR 包或便携 tar.gz 二选一

Arch / Manjaro装 AUR 包（需先装好yay或paru）：

yay -S folia-major-bin # 拉取并安装薄封装包

它是薄封装：构建时去 Releases 拉folia-major-<版本>-linux-x64.tar.gz，放进/opt/folia-major，再建usr/bin/folia-major链接和菜单项。依赖清单（alsa-lib、gtk3、libxss、nss）都能在 packaging/aur/folia-major-bin/PKGBUILD 里核对。构建长时间卡在下载步骤，就是「国内下载 GitHub 慢」的同一问题，直接转下面的便携版。

Debian / Ubuntu / Fedora 及其他：.deb、.rpm或linux-x64的 tar.gz 任选：

tar -xzf folia-major-0.7.23-linux-x64.tar.gz # 解压出可执行文件、图标和桌面模板 ./folia-major # 首次启动确认渲染正常再集成

想进应用菜单：把resources/linux/folia-major.desktop复制到~/.local/share/applications/，把文件里的__APP_PATH__和__ICON_PATH__替换成可执行文件和resources/linux/icon.png的绝对路径；桌面环境要求时再标记为可信或可执行。模板原文见 packaging/linux/README-LINUX.txt。

NAS / 服务器：两个文件拉起 Docker 全栈

想在手机或浏览器里用，走 Web 版。要求 Docker Engine 24+ 与 Compose v2。不用克隆整个仓库，新建空目录，放 deploy/docker/compose.yaml 和同目录的.env模板（deploy/docker/README.md 有完整说明）：

openssl rand -hex 32 # 生成随机串，填入 .env 的 SYNC_TOKEN（至少 8 位） docker compose config # 校验配置，变量缺失在这里直接报错 docker compose pull # 拉取镜像 docker compose up -d --wait # 后台启动并等待健康检查通过

默认 Web 网关在18080，Sync Server 在13000。.env里SYNC_TOKEN是必填项（缺失时 Compose 拒绝启动），FOLIA_IMAGE_NAMESPACE决定从哪个命名空间拉镜像，留默认官方值即可。正式用本地音乐目录导入需要可信 HTTPS：让 NAS 的反向代理终止证书（https://域名 → 127.0.0.1:18080），纯局域网 HTTP 下该功能不可用，原因和代理配置细节都写在部署文档里。只想跑 Sync Server（多台设备同步外观与 AI 主题库）的话，单独入口是docker compose -f deploy/docker/compose.sync.yaml up -d --build。

没有 Docker 的受限环境，也可以从源码起本地服务（需 Node.js ≥ 24，版本号以 package.json 的engines为准）：

git clone https://gitcode.com/GitHub_Trending/fo/folia-major cd folia-major npm install # 安装依赖 npm run dev # Vite 本地开发服务器，浏览器访问对应端口

npm run dev适合体验和调试；正式对外服务仍建议走 Docker。

装完立刻做的两个检查

桌面版：打开应用看版本，启动或「关于」界面显示的版本号应与下载文件名一致（当前0.7.23），不一致说明装的是旧包，直接重下。再找一首带逐字歌词的歌丢进去，全屏歌词动画正常出字，说明 WebGPU 渲染链路是通的。

Web 部署：docker compose ps全部服务应为 healthy，然后curl http://NAS-IP:18080/healthz和curl http://NAS-IP:13000/health都应返回正常。这两个接口通了，浏览器打开http://NAS-IP:18080应该能看到登录页和首页。

跑不起来：六个高频问题

症状	原因	解法
从 Releases 下载慢或中断	到 GitHub 链路差	转 README「快速下载」的网盘镜像（夸克 / 百度，提取码`flia`），核对版本号
macOS 弹「应用已损坏」	无 Developer ID 签名 + 下载隔离标记	`xattr -dr com.apple.quarantine /Applications/Folia.app`后从 Applications 重新打开
Linux 黑屏、透明度或模糊异常	GPU 路径与显卡驱动不兼容	换软件渲染`FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major`；仍不稳定再退到`=software`
AUR 构建长时间卡在下载	构建脚本在拉 Releases 的 tar.gz	别等，转便携版 tar.gz 手动部署
Docker 起不来或容器反复重启	`SYNC_TOKEN`未填 / 太短，或`.env`变量缺失	`docker compose config`定位缺失项；token 用`openssl rand -hex 32`重新生成
便携版菜单项点不了、图标缺失	可执行文件被移走，`resources/`与主程序不在同一目录	保持解压目录结构完整，再按桌面模板重填`Exec`与`Icon`的绝对路径