Folia 安装指南桌面与 NAS 三种方式跑通全屏歌词动画播放器【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-majorFolia 是一个把歌词渲染成全屏动画的音乐播放器支持网易云、QQ 音乐、酷狗、Navidrome 和本地曲库。这篇文章只解决一件事如何安装 Folia 桌面版或在服务器上用 Docker 部署 Folia Web 版以及出问题该往哪查。装完你能得到一个开箱即用的歌词动画播放器Docker 路线还额外得到一部手机/浏览器可访问的 Web 版。用三个问题选定你的安装路线连续回答三个问题每个都有明确答案跑在哪自己的电脑 → 桌面版NAS 或服务器、给手机浏览器访问 → Web 版Docker。什么系统Windows / macOS → 直接拿项目 Releases 页的官方安装包Linux → 便携版 tar.gz 最稳Debian/Fedora 可选.deb/.rpm。装不接受装 Docker接受 → 用 Docker Compose 全栈部署两个文件就够不接受 → 走源码本地服务模式或云部署平台。平台包格式最小验证动作WindowsFolia-Setup-0.7.23.exe启动核对版本号 0.7.23macOSApple silicon / IntelFolia-0.7.23-arm64.dmg/Folia-0.7.23-x64.dmgxattr去隔离后启动Debian / Fedora / 其他.deb/.rpm/linux-x64.tar.gz首次启动能正常渲染Arch / ManjaroAURfolia-major-binyay -Si确认包完整NAS / 服务器Docker Composedocker compose ps全 healthy主推官方安装包装桌面版这条路线最省事先走它。桌面版内置前后端运行环境不需要 Node.js装完即用当前版本 0.7.23以 package.json 为准。Windows装 .exe 一步到位去项目 Releases 页取Folia-Setup-0.7.23.exe双击按向导走完即可。如果下载慢到掉线别干等README.md「快速下载」一节挂了夸克网盘和百度镜像提取码flia国内直连快很多。注意网盘只有 Windows 和 Apple silicon 两个安装包且版本可能滞后取下来先对一眼版本号。macOS.dmg 之后一条命令放行Releases 取.dmgApple silicon 选arm64Intel 选x64把Folia.app拖进Applications再启动。首次打开基本会弹「应用已损坏」当前发布没有 Apple Developer ID 签名浏览器下载的文件又带隔离属性Gatekeeper 就把未签名应用显示成「已损坏」。终端执行xattr -dr com.apple.quarantine /Applications/Folia.app # 移除下载隔离属性两种拦截提示都适用跑完从 Applications 重新打开。macOS 版暂不支持应用内自动更新每次覆盖安装后这条命令要再跑一次。提示的是「无法验证」而不是「已损坏」常见于 Intel时可改走系统设置 → 隐私与安全性 →「仍要打开」分支细节见 docs/desktop/macos-app-damaged.md。Linux 三种拿法tar -xzf folia-major-0.7.23-linux-x64.tar.gz # 解压便携版得到可执行文件、图标与桌面模板 ./folia-major # 首次启动确认能正常渲染再做后续集成Debian / Ubuntu 取.debFedora 取.rpm都不合适就用上面的 tar.gz 便携版。Arch / Manjaro 可yay -S folia-major-bin依赖与流程见 packaging/aur/folia-major-bin/PKGBUILD。但 AUR 包pkgver还是 0.1.4落后于 release构建时要从 Releases 拉 tar.gz长时间卡下载就停手转便携版。想进应用菜单把resources/linux/folia-major.desktop复制到~/.local/share/applications/替换__APP_PATH__与__ICON_PATH__两个占位符模板说明见 packaging/linux/README-LINUX.txt。Folia Docker 部署Web 版上 NAS要求 Docker Engine 24 与 Compose v2。不用克隆整个仓库空目录放两个文件——deploy/docker/compose.yaml 和同目录的 deploy/docker/.env.example 改名成的.env。openssl rand -hex 32 # 生成随机串作为 SYNC_TOKEN 的取值把结果填进.env的SYNC_TOKEN至少 8 位必填缺失会直接拒绝启动FOLIA_IMAGE_NAMESPACE留默认papersman即可。然后docker compose config # 校验配置变量缺失在这里直接报错 docker compose pull # 拉取全部镜像 docker compose up -d --wait # 后台启动并等待健康检查通过默认 Web 网关在18080端口Sync Server 在13000多台设备同步外观与 AI 主题库用。正式用本地音乐目录导入需要可信 HTTPS让 NAS 反向代理终止证书https://你的域名 → 127.0.0.1:18080纯局域网 HTTP 下该功能不可用代理配置细节见 deploy/docker/README.md。只想单独跑 Sync Serverdocker 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.git # 拉取源码 cd folia-major npm install # 安装依赖 npm run dev # Vite 开发服务器监听 3000 端口装完快速自查确认它跑起来了别直接听歌先过一遍清单桌面版启动应用「关于」界面显示的版本号与下载文件名一致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能看到登录页和首页。常见坑与怎么解Linux 启动黑屏、透明度或模糊异常。GPU 路径与显卡驱动不兼容。先换软件光栅化FOLIA_LINUX_GRAPHICS_MODEswiftshader ./folia-major仍闪烁再退到FOLIA_LINUX_GRAPHICS_MODEsoftware ./folia-major。排查前先确认可执行文件还在便携包目录里、和resources/挨着。从 Releases 下载慢或中途断开。到 GitHub 的链路差不是包的问题。转 README.md「快速下载」的网盘镜像夸克 / 百度提取码flia取下来核对版本号再装。Docker 起不来ps报错或容器反复重启。十有八九是SYNC_TOKEN没填或不足 8 位compose.yaml里写着SYNC_TOKEN: ${SYNC_TOKEN:?Set SYNC_TOKEN to at least 8 characters}缺了栈直接拒启动。用docker compose config定位缺失项token 用openssl rand -hex 32重新生成。AUR 装完应用列表里没有 Folia。AUR 包版本落后或下载中断导致包未装全。yay -Si folia-major-bin重装一次仍失败就查 PKGBUILD 里的下载地址能否连通查不通直接放弃 AUR 改手动部署 tar.gz。便携版启动后菜单项点不了、图标缺失。可执行文件被移走resources/与主程序不在同一目录。恢复解压目录的完整结构再按桌面模板把Exec与Icon重填成实际绝对路径。还想深入桌面端细节、Wayland 壁纸模式、遥控窗配置docs/technical.mdDocker 环境变量、QQ 登录态、Navidrome 预置账号deploy/docker/README.md本地音乐库的导入、重扫与在线匹配docs/local-library-management.md装好之后把一首带逐字歌词的歌丢进去全屏动画见分晓 【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考