Folia 歌词动画播放器安装部署指南桌面端、Docker 全栈与源码体验 3 条路线【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-majorFolia 把歌词渲染成全屏动画支持网易云、QQ 音乐、酷狗、Navidrome 与本地曲库。本文按桌面端、Docker 全栈、源码体验 3 条路线给出安装与部署步骤帮你选对路线、跟完操作、验证跑通。按场景选部署路线桌面版和 Web 版的能力边界与依赖完全不同选错路线会白折腾。先花十秒对一下自己的使用场景你在哪用走哪条路线动手前备好的东西自己的电脑想要装完就用的完整体验路线一桌面版安装包Windows / macOS / Linux 任一系统macOS 需能打开终端NAS 或服务器想在手机和浏览器里听路线二Docker Compose 全栈Docker Engine 24 与 Compose v218080、13000 端口空闲想先看看效果、顺便读源码路线三源码跑本地 Web 版Node.js 24 与 npm路线一桌面版安装包下载与安装步骤前置当前版本 0.7.23安装包在项目 Releases 页面Windows 取Folia-Setup-0.7.23.exemacOS 取Folia-0.7.23-arm64.dmgApple 芯片或Folia-0.7.23-x64.dmgIntelLinux 按发行版选.deb、.rpm或便携 tar.gz。桌面版内置前后端运行环境不需要 Node.js 或任何额外运行时。步骤下载对应平台的安装包Windows 按向导装完即可macOS 把Folia.app拖进Applications再启动别在挂载的 dmg 里直接运行。macOS 首次打开若弹「应用已损坏」这是发布未带 Developer ID 签名加上下载隔离标记在终端执行xattr -dr com.apple.quarantine /Applications/Folia.app # 移除下载隔离属性两种拦截提示都适用再从 Applications 重新打开。macOS 版暂不支持应用内自动更新每装一次新版都要重跑这条命令。 3. Arch / Manjaro 可以直接走 AURyay -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 # 首次启动确认能正常渲染想进应用菜单把包内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_MODEswiftshader ./folia-major重启仍不稳定再退到software变量含义见 packaging/linux/README-LINUX.txt。路线二Docker Compose 部署 Web 全栈到服务器前置装好 Docker Engine 24 与 Compose v2部署不用克隆仓库空目录里只需要两个文件。对外只发布两个端口Web 网关 18080、Sync Server 13000其余容器仅在 Docker 网络内互访。步骤建一个空目录把 deploy/docker/compose.yaml全栈服务定义和同目录的.env.example变量模板改名为.env放进去。生成同步令牌openssl rand -hex 32 # 输出一串随机字符串把输出填入.env的SYNC_TOKEN必填至少 8 位FOLIA_IMAGE_NAMESPACE保留模板默认值papersmanAI 相关变量可留空不影响播放。 3. 校验并启动docker compose config # 变量缺失会在这里直接报错不用等容器启动才发现 docker compose pull docker compose up -d --wait # 后台启动并等待健康检查通过逐项确认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 方案。步骤克隆仓库git clone https://gitcode.com/GitHub_Trending/fo/folia-major cd folia-major安装依赖npm install # 安装全部前端依赖启动开发服务器npm run dev # Vite 开发服务器默认监听 0.0.0.0:3000浏览器打开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卡住了看这里你看到的多半是现在做从 Releases 下载慢或中途断开网络链路不稳换稳定网络重下并核对文件完整残缺包过不了 Gatekeeper 也解不开Linux 启动黑屏、透明/模糊异常显卡驱动与渲染路径不匹配FOLIA_LINUX_GRAPHICS_MODEswiftshader重启仍不行用software见 packaging/linux/README-LINUX.txtmacOS 提示「应用已损坏」或「无法验证」未带 Developer ID 签名 下载隔离属性跑xattr -dr com.apple.quarantine /Applications/Folia.app后从 Applications 启动分支细节见 docs/desktop/macos-app-damaged.mdAUR 装完后应用列表里没有 FoliaAUR 包是薄封装且版本滞后构建时拉 tar.gz 可能失败yay -Si folia-major-bin重装一次仍失败就改走便携 tar.gz 手动部署docker compose config报Set SYNC_TOKEN/Set FOLIA_IMAGE_NAMESPACE.env配置项缺失填上SYNC_TOKEN至少 8 位与镜像命名空间默认papersman后重新校验容器起来后反复重启同步令牌为空或太短用openssl rand -hex 32重新生成后docker compose up -d --waitnpm run dev提示 Node 版本不满足本地 Node 低于 24升级到 Node.js 24node -v确认后再装依赖浏览器里本地音乐目录导入不可用纯 HTTP 不属于安全上下文反向代理终止 HTTPS 后再访问配置见 deploy/docker/README.md装完之后这些文档接着看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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Folia 歌词动画播放器安装部署指南桌面端、Docker 全栈与源码体验 3 条路线【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-majorFolia 把歌词渲染成全屏动画支持网易云、QQ 音乐、酷狗、Navidrome 与本地曲库。本文按桌面端、Docker 全栈、源码体验 3 条路线给出安装与部署步骤帮你选对路线、跟完操作、验证跑通。按场景选部署路线桌面版和 Web 版的能力边界与依赖完全不同选错路线会白折腾。先花十秒对一下自己的使用场景你在哪用走哪条路线动手前备好的东西自己的电脑想要装完就用的完整体验路线一桌面版安装包Windows / macOS / Linux 任一系统macOS 需能打开终端NAS 或服务器想在手机和浏览器里听路线二Docker Compose 全栈Docker Engine 24 与 Compose v218080、13000 端口空闲想先看看效果、顺便读源码路线三源码跑本地 Web 版Node.js 24 与 npm路线一桌面版安装包下载与安装步骤前置当前版本 0.7.23安装包在项目 Releases 页面Windows 取Folia-Setup-0.7.23.exemacOS 取Folia-0.7.23-arm64.dmgApple 芯片或Folia-0.7.23-x64.dmgIntelLinux 按发行版选.deb、.rpm或便携 tar.gz。桌面版内置前后端运行环境不需要 Node.js 或任何额外运行时。步骤下载对应平台的安装包Windows 按向导装完即可macOS 把Folia.app拖进Applications再启动别在挂载的 dmg 里直接运行。macOS 首次打开若弹「应用已损坏」这是发布未带 Developer ID 签名加上下载隔离标记在终端执行xattr -dr com.apple.quarantine /Applications/Folia.app # 移除下载隔离属性两种拦截提示都适用再从 Applications 重新打开。macOS 版暂不支持应用内自动更新每装一次新版都要重跑这条命令。 3. Arch / Manjaro 可以直接走 AURyay -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 # 首次启动确认能正常渲染想进应用菜单把包内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_MODEswiftshader ./folia-major重启仍不稳定再退到software变量含义见 packaging/linux/README-LINUX.txt。路线二Docker Compose 部署 Web 全栈到服务器前置装好 Docker Engine 24 与 Compose v2部署不用克隆仓库空目录里只需要两个文件。对外只发布两个端口Web 网关 18080、Sync Server 13000其余容器仅在 Docker 网络内互访。步骤建一个空目录把 deploy/docker/compose.yaml全栈服务定义和同目录的.env.example变量模板改名为.env放进去。生成同步令牌openssl rand -hex 32 # 输出一串随机字符串把输出填入.env的SYNC_TOKEN必填至少 8 位FOLIA_IMAGE_NAMESPACE保留模板默认值papersmanAI 相关变量可留空不影响播放。 3. 校验并启动docker compose config # 变量缺失会在这里直接报错不用等容器启动才发现 docker compose pull docker compose up -d --wait # 后台启动并等待健康检查通过逐项确认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 方案。步骤克隆仓库git clone https://gitcode.com/GitHub_Trending/fo/folia-major cd folia-major安装依赖npm install # 安装全部前端依赖启动开发服务器npm run dev # Vite 开发服务器默认监听 0.0.0.0:3000浏览器打开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卡住了看这里你看到的多半是现在做从 Releases 下载慢或中途断开网络链路不稳换稳定网络重下并核对文件完整残缺包过不了 Gatekeeper 也解不开Linux 启动黑屏、透明/模糊异常显卡驱动与渲染路径不匹配FOLIA_LINUX_GRAPHICS_MODEswiftshader重启仍不行用software见 packaging/linux/README-LINUX.txtmacOS 提示「应用已损坏」或「无法验证」未带 Developer ID 签名 下载隔离属性跑xattr -dr com.apple.quarantine /Applications/Folia.app后从 Applications 启动分支细节见 docs/desktop/macos-app-damaged.mdAUR 装完后应用列表里没有 FoliaAUR 包是薄封装且版本滞后构建时拉 tar.gz 可能失败yay -Si folia-major-bin重装一次仍失败就改走便携 tar.gz 手动部署docker compose config报Set SYNC_TOKEN/Set FOLIA_IMAGE_NAMESPACE.env配置项缺失填上SYNC_TOKEN至少 8 位与镜像命名空间默认papersman后重新校验容器起来后反复重启同步令牌为空或太短用openssl rand -hex 32重新生成后docker compose up -d --waitnpm run dev提示 Node 版本不满足本地 Node 低于 24升级到 Node.js 24node -v确认后再装依赖浏览器里本地音乐目录导入不可用纯 HTTP 不属于安全上下文反向代理终止 HTTPS 后再访问配置见 deploy/docker/README.md装完之后这些文档接着看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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
