Folia 安装指南：五种路线一次装对，桌面到 NAS 全打通

Folia 安装指南：五种路线一次装对，桌面到 NAS 全打通

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

先回答一道选择题：你打算在哪里听 Folia？答案只有两种——本机桌面，或者NAS / 服务器上的浏览器。这道题决定路线，别选反了。

Folia 是一款全屏歌词动画播放器：本地音乐库能导入，网易云、QQ 音乐、酷狗等在线音源也能直接搜来播放，歌词会铺满整块屏幕做沉浸动画。它有两个形态——Electron 打包的桌面版（Windows、macOS、Linux），和跑在浏览器里的 Web 版。桌面版内置前后端运行环境，装完即用；Web 版面向多设备访问，适合部署在 NAS 上。本文当前仓库版本为 0.7.23，实际文件名请以 Releases 页面为准。

选路线：一张表看懂五种安装路径

国内网络直连 GitHub Releases 困难时，README「快速下载」一节提供了夸克 / 百度两个网盘入口。注意网盘只镜像了 Windows 安装包和 Apple silicon 的 dmg，Intel Mac 与 Linux 包必须走 Releases，下载前先核对文件名里的版本号。

省：装完想快速感受效果，播放任意带歌词的歌再点全屏按钮，流光（Lumi）这类主题最直观。

Windows：下 exe，跑完安装向导

下载。去 Releases 页面拿Folia-Setup-<版本>.exe；直连慢就改用官方网盘。网盘用户建议先把文件转存进自己的网盘空间再拉下来，中途断了能续传。

安装。双击后是标准 NSIS 向导，安装目录可以改，其余一路确认。程序本身携带全部运行环境，不需要单独装 Node 或 Electron。

启动。装完从开始菜单点开，桌面端细节（Wayland 遥控窗等）见 Linux 与桌面端技术说明。

坑：只装官方渠道的分发文件。来路不明的第三方转包一律不要碰。

macOS：先认芯片，再挑 dmg

下载。点「关于本机」确认芯片：Apple silicon 拿Folia-<版本>-arm64.dmg，Intel 拿Folia-<版本>-x64.dmg。记住一点——网盘只有 arm64 版，Intel Mac 只能走 Releases。

安装。打开 dmg，把Folia.app拖进Applications，之后关掉挂载盘，只运行 Applications 里的正式应用。

启动。首次打开如果弹出「已损坏」或「无法验证」，这不是真的坏了：应用缺少 Apple Developer ID 签名，被 Gatekeeper 拦下。终端执行下面这条命令，再重新打开即可：

xattr -dr com.apple.quarantine /Applications/Folia.app

更完整的原理和「隐私与安全性」备选操作，见 macOS 提示应用已损坏的处理文档。

坑：macOS 版暂时不支持应用内自动更新，每次覆盖安装新版 dmg 后，上面那条xattr命令都要再跑一次。

Arch 系：AUR 一行命令装 folia-major

下载 + 安装合并成一条命令。确认已装 yay 或 paru：

yay -S folia-major-bin

paru 用户把包管理器换成paru -S folia-major-bin即可。构建完成后，alsa-lib、gtk3、libxss、nss四个依赖自动解决，程序放进/opt/folia-major，菜单启动项一并生成，启动时直接点图标。

坑：这个包是基于预编译 Release 打出来的（PKGBUILD），版本通常比最新发行慢半拍，构建时还要从 Releases 拉 Linux 压缩包。网络慢就先手动下载同版本folia-major-<版本>-linux-x64.tar.gz放进源码目录，再执行makepkg -si。

其他 Linux：便携 tar.gz，解压即播

下载。Releases 页面拿folia-major-<版本>-linux-x64.tar.gz。

安装。解压到任意目录，包里三样东西：folia-major可执行文件、resources/linux/icon.png、resources/linux/folia-major.desktop。要桌面启动项的话，把.desktop复制到~/.local/share/applications/，把里面的__APP_PATH__和__ICON_PATH__换成可执行文件和图标文件的绝对路径，再按桌面环境要求标记为可信。完整说明见 Linux 便携版说明。

启动。

./folia-major

坑：启动黑屏、透明度异常或 GPU 进程崩溃，先换渲染路径：

FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major

还不行就切到最保守的软件渲染，把值改成software。X11 下如果「智能动感模式」提示没有可用的 WebGPU，可以手动开 Vulkan：FOLIA_LINUX_VULKAN=1 ./folia-major --ozone-platform=x11。原生 Wayland 下别开 Vulkan，那个变量会被忽略，开了反而容易崩。

Docker 自托管：把 Folia 装进 NAS

这一节给想让手机和电脑都打开同一个 Folia 的人。要求 Docker Engine 24+ 与 Compose v2，完整细节见 Docker Compose 全栈部署文档。

下载。不拉源码，只在一个空目录里放两个文件：compose.yaml和.env模板（README「获取方式」给了下载地址）。

安装。先生成同步令牌，再填进.env的SYNC_TOKEN：

openssl rand -hex 32

然后验证配置并启动：

docker compose config docker compose up -d --wait

启动与访问。浏览器打开http://NAS-IP:18080就是 Web 端；http://NAS-IP:13000/health用来确认 Sync Server 活着。网易云、酷狗、QQ 音乐接口都没有对外端口，全部走 gateway 转发，这是刻意的安全设计。

坑：局域网 IP 上的普通 HTTP 不属于浏览器安全上下文，本地音乐目录导入等功能会不可用。正式用本地曲库的话，让 NAS 的反向代理终止 HTTPS（证书链必须完整合法），再把绑定地址收到127.0.0.1。AI 配置留空即可，不影响播放。

装好之后的验收清单

1. 启动 Folia，在「关于」页核对版本号，应与你下载的文件名一致。
2. 登录一个在线音源（网易云 / QQ / 酷狗），或导入一个本地音乐文件夹。
3. 播放一首带歌词的歌，进入全屏歌词动画，确认渲染正常、不卡帧。

三条都过，安装就算完成。

出问题时按症状对号入座

下载一直断或慢得离谱。先试：Windows 和 Apple silicon Mac 用户直接切官方网盘，支持断点续传。还不行：Intel Mac 与 Linux 用户改走 Releases，挑网络空闲时段拉；Arch 用户也可以先手动下好 tar.gz 再本地构建 AUR 包。

macOS 弹窗说应用已损坏。先试：终端跑xattr -dr com.apple.quarantine /Applications/Folia.app后重新打开。还不行：确认你运行的是Applications里的应用，而不是 dmg 挂载盘里的临时副本；文件不完整就重新下载一次。

Linux 黑屏、透明效果发虚、GPU 进程闪退。先试：FOLIA_LINUX_GRAPHICS_MODE=swiftshader前缀启动。还不行：换成software跑通再说。若只是 X11 下 WebGPU 不可用，按上文加FOLIA_LINUX_VULKAN=1参数，Wayland 下忽略此条。

装出来的版本号比最新 Release 旧。先试：把文件名里的版本号与 Releases 页最新值对比，不一致就直接下官方最新包。还不行：网盘镜像和 AUR 包天然滞后，别在旧渠道上反复试，AUR 用户手动下 tar.gz 本地构建最快。

现在，按你的系统回到「选路线」那张表，把对应的压缩包或镜像拖进手里——Windows 装向导、macOS 拖应用、Linux 敲回车、NAS 跑 compose，验收清单三条全绿，全屏歌词动画就是你的了。

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