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-majorFolia 是一个 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 v2docker --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 选 arm64Intel 选 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 取.debFedora / 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_TOKENopenssl 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_MODEswiftshader ./folia-major # 以 swiftshader 软件渲染方式启动 FOLIA_LINUX_GRAPHICS_MODEsoftware ./folia-major # 仍不稳定时用最保守的软件渲染档位恢复正常后改回FOLIA_LINUX_GRAPHICS_MODEsystem。X11 下 WebGPU 不可用的场景可用FOLIA_LINUX_VULKAN1 ./folia-major --ozone-platformx11手动开 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），仅供参考
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-majorFolia 是一个 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 v2docker --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 选 arm64Intel 选 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 取.debFedora / 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_TOKENopenssl 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_MODEswiftshader ./folia-major # 以 swiftshader 软件渲染方式启动 FOLIA_LINUX_GRAPHICS_MODEsoftware ./folia-major # 仍不稳定时用最保守的软件渲染档位恢复正常后改回FOLIA_LINUX_GRAPHICS_MODEsystem。X11 下 WebGPU 不可用的场景可用FOLIA_LINUX_VULKAN1 ./folia-major --ozone-platformx11手动开 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），仅供参考
