Folia 歌词动画播放器安装部署指南：桌面端、Docker 全栈与源码体验 3 条路线

Folia 歌词动画播放器安装部署指南：桌面端、Docker 全栈与源码体验 3 条路线

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

Folia 把歌词渲染成全屏动画，支持网易云、QQ 音乐、酷狗、Navidrome 与本地曲库。本文按桌面端、Docker 全栈、源码体验 3 条路线给出安装与部署步骤，帮你选对路线、跟完操作、验证跑通。

按场景选部署路线

桌面版和 Web 版的能力边界与依赖完全不同，选错路线会白折腾。先花十秒对一下自己的使用场景：

路线一：桌面版安装包下载与安装步骤

前置

• 当前版本 0.7.23，安装包在项目 Releases 页面：Windows 取Folia-Setup-0.7.23.exe，macOS 取Folia-0.7.23-arm64.dmg（Apple 芯片）或Folia-0.7.23-x64.dmg（Intel），Linux 按发行版选.deb、.rpm或便携 tar.gz。
• 桌面版内置前后端运行环境，不需要 Node.js 或任何额外运行时。

步骤

1. 下载对应平台的安装包，Windows 按向导装完即可；macOS 把Folia.app拖进Applications再启动，别在挂载的 dmg 里直接运行。
2. macOS 首次打开若弹「应用已损坏」，这是发布未带 Developer ID 签名加上下载隔离标记，在终端执行：

xattr -dr com.apple.quarantine /Applications/Folia.app # 移除下载隔离属性，两种拦截提示都适用

再从 Applications 重新打开。macOS 版暂不支持应用内自动更新，每装一次新版都要重跑这条命令。 3. Arch / Manjaro 可以直接走 AUR：

yay -S folia-major-bin # 薄封装：构建时去 Releases 拉预构建 tar.gz，装进 /opt/folia-major

注意 packaging/aur/folia-major-bin/PKGBUILD 当前锁定的是 0.1.4 的 tar.gz，版本会滞后于最新 release，介意新特性就跳过去用下面的便携版。 4. 其他发行版用便携版手动装：

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

5. 想进应用菜单，把包内resources/linux/folia-major.desktop复制到~/.local/share/applications/，再替换文件里的__APP_PATH__（可执行文件绝对路径）与__ICON_PATH__（图标绝对路径），模板说明在 packaging/linux/README-LINUX.txt。

完成信号

「关于」界面显示的版本号与下载文件名一致（0.7.23）；放一首带逐字歌词的歌，全屏歌词动画逐字出字，说明 WebGPU 渲染链路是通的。

卡点提示

• 从 Releases 下载慢或中途断开：多半是网络链路问题，换个稳定网络重下；文件不完整时 Gatekeeper 会拦截、tar.gz 会解不开。
• Linux 启动黑屏、透明度或模糊异常：换FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major重启，仍不稳定再退到=software，变量含义见 packaging/linux/README-LINUX.txt。

路线二：Docker Compose 部署 Web 全栈到服务器

前置

• 装好 Docker Engine 24+ 与 Compose v2；部署不用克隆仓库，空目录里只需要两个文件。
• 对外只发布两个端口：Web 网关 18080、Sync Server 13000，其余容器仅在 Docker 网络内互访。

步骤

1. 建一个空目录，把 deploy/docker/compose.yaml（全栈服务定义）和同目录的.env.example（变量模板，改名为.env）放进去。
2. 生成同步令牌：

openssl rand -hex 32 # 输出一串随机字符串

把输出填入.env的SYNC_TOKEN（必填，至少 8 位）；FOLIA_IMAGE_NAMESPACE保留模板默认值papersman，AI 相关变量可留空，不影响播放。 3. 校验并启动：

docker compose config # 变量缺失会在这里直接报错，不用等容器启动才发现 docker compose pull docker compose up -d --wait # 后台启动并等待健康检查通过

4. 逐项确认：

docker compose ps # 看各容器状态 curl http://NAS-IP:18080/healthz # Web 网关健康检查 curl http://NAS-IP:13000/health # Sync Server 健康检查

完成信号

docker compose ps里全部服务显示 healthy，上面两个健康检查地址都返回正常；浏览器打开http://NAS-IP:18080能看到登录页和首页。

卡点提示

• docker compose config报Set SYNC_TOKEN或Set FOLIA_IMAGE_NAMESPACE：说明.env对应项为空，前者填至少 8 位随机串，后者留模板默认值即可。
• 纯局域网 HTTP 能搜索播放，但本地音乐目录导入按钮不可用：File System Access API 要求可信 HTTPS 安全上下文，让 NAS 反向代理终止证书并指向127.0.0.1:18080，配置细节见 deploy/docker/README.md 的「HTTPS 与浏览器安全上下文」一节。

只想单独跑 Sync Server（多台设备同步外观与 AI 主题库）的话，在仓库根目录执行docker compose -f deploy/docker/compose.sync.yaml up -d --build。

路线三：从源码跑通本地 Web 版体验

前置

• Node.js 24 或更高（package.json 的engines声明>=24.0.0），用node -v核对。
• 这条路线适合体验和调试；正式对外服务仍建议走 Docker 方案。

步骤

1. 克隆仓库：

git clone https://gitcode.com/GitHub_Trending/fo/folia-major cd folia-major

2. 安装依赖：

npm install # 安装全部前端依赖

3. 启动开发服务器：

npm run dev # Vite 开发服务器，默认监听 0.0.0.0:3000

4. 浏览器打开http://localhost:3000。

完成信号

浏览器出现 Folia 首页；放一首带逐字歌词的歌，全屏动画逐字出字、排版正常，说明渲染链路在工作。

卡点提示

• npm run dev报 Node 版本相关错误：本地 Node 低于 24，先升级再装依赖。
• 开发服务器裸启动时在线平台无法播放：Web 版需要把网易云 API 地址、AI 密钥等变量写进.env.local，逐项说明见 docs/technical.md 的「本地开发」变量表。

验收清单：确认环境真的跑通

• 桌面版「关于」界面的版本号与下载文件名一致，确认没装到旧包
• 带逐字歌词的歌曲能播放，全屏歌词动画逐字出字，无黑屏或模糊
• Web 部署时docker compose ps全部 healthy，没有容器反复重启
• 18080 的/healthz与 13000 的/health都能正常返回
• 浏览器打开网关地址能看到登录与首页；需要用本地目录导入的，确认站点走的是 HTTPS

卡住了看这里

装完之后：这些文档接着看

• docs/technical.md：调 Wayland 壁纸模式、遥控窗、常用开发脚本时看它
• deploy/docker/README.md：改 Docker 环境变量、QQ 登录态、Navidrome 预置账号时看它
• docs/local-library-management.md：做本地曲库导入、重扫与在线元数据匹配时看它

把一首带逐字歌词的歌丢进去，全屏动画跑起来的那一刻，部署就算真正完成了 🎵

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