Folia 安装完整指南：四条路线快速装好全屏歌词动画播放器

Folia 安装完整指南：四条路线快速装好全屏歌词动画播放器

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

Folia 是一款把歌词渲染成全屏沉浸动画的桌面播放器，能接本地音乐库，也能登录网易云、QQ 音乐、酷狗在线音源。这篇 Folia 安装教程只解决一件事：把安装包下载到你的机器并跑起来。顺利的话，十来分钟就能装完。

先确认你走哪条路线

动手前先问自己三个问题：

1. 你在什么系统上？Windows、macOS、Linux 各走各的包；Linux 用户再细分一步——Arch 系（Arch / EndeavourOS）走 AUR，其他发行版走便携压缩包。
2. Mac 是什么芯片？点左上角「关于本机」看是 Apple silicon（arm64）还是 Intel（x64），两种芯片的安装包文件名不同，选错了装不了。
3. 能不能直连官方 Releases 页？直连没问题的话版本最新、平台最全；直连慢或断流时，Windows 和 Apple silicon Mac 用户有官方网盘（夸克 / 百度）兜底，但网盘只有这两个平台的包，且通常只收 Windows 与 arm64 Mac 的正式版。

四条路线速览，对号入座即可：

• 官方 Releases 直连——Windows / macOS / Linux 全覆盖，版本最新，约 10-20 分钟。
• 官方网盘镜像——只覆盖 Windows 和 arm64 Mac，国内直连快、支持断点续传，约 5-10 分钟。建议先把文件转存到自己网盘再下载。
• AUR 包folia-major-bin——Arch / EndeavourOS 专用，一条命令装完，约 3-5 分钟，但版本通常落后官方发行。
• Docker Web 自托管——面向 NAS / 服务器，让手机和浏览器都能访问，30 分钟起步。

仓库版本目前是 0.7.23，但具体下哪个包，永远以官方 Releases 页最新一条为准。

桌面安装

Folia Windows 安装：下载 exe 跑完向导

去哪下：去 Releases 页拿Folia-Setup-<版本>.exe；走网盘的话拿同名文件，记得先转存再下载，中途断了也能续传。

怎么装：双击安装程序，这是 NSIS 向导，中途可以修改安装目录，其余一路确认即可。桌面版把前后端运行环境都打进了包里，装完从开始菜单启动就行，不用额外装运行时。

容易卡住：只装官方渠道的分发文件，网上来路不明的转发包一律不碰。

Folia macOS 安装：按芯片选 dmg，再拖进 Applications

去哪下：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

原理和「隐私与安全性」的备选方案写在仓库的 docs/desktop/macos-app-damaged.md。💡 另一个要记住的点：macOS 版目前不支持应用内自动更新，以后每次用新 dmg 覆盖安装，都要把这行xattr命令重跑一遍。

Folia Linux 安装：便携包与 AUR

Ubuntu / Debian / Fedora：便携版 tar.gz 直接启动

去哪下：从 Releases 页拿folia-major-<版本>-linux-x64.tar.gz。

怎么装：解压到任意目录，进目录直接启动：

./folia-major

想生成桌面启动项的话，把包内的resources/linux/folia-major.desktop复制到~/.local/share/applications/，再把模板里的__APP_PATH__和__ICON_PATH__两个占位符替换为可执行文件和resources/linux/icon.png的绝对路径，最后按你的桌面环境要求把这个启动项标记为可信即可。完整说明和图形环境变量参考 packaging/linux/README-LINUX.txt。

Arch 系 AUR：一条命令装完

装好 yay 或 paru 之后执行：

yay -S folia-major-bin

paru 用户把命令换成paru -S folia-major-bin即可。构建过程会自动解决alsa-lib、gtk3、libxss、nss四个依赖，程序装进/opt/folia-major并生成菜单启动项。

⚠️ 这个 AUR 包是基于预编译 Release 打的包，依赖清单见 packaging/aur/folia-major-bin/PKGBUILD，所以版本一般落后官方最新发行。如果你的网络拉 Releases 很慢，可以先把同版本的folia-major-<版本>-linux-x64.tar.gz手动下好放进 AUR 源码目录，再执行makepkg -si本地构建。

Linux 图形排障

启动后黑屏、透明度异常或直接闪退，多半是 GPU 兼容问题。按这个顺序试：

FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major FOLIA_LINUX_GRAPHICS_MODE=software ./folia-major

X11 环境下如果 WebGPU 不可用，可以用 Vulkan 路线替代：

FOLIA_LINUX_VULKAN=1 ./folia-major --ozone-platform=x11

注意：原生 Wayland 下不要开这个 Vulkan 选项，只针对 X11 使用。

让手机和浏览器也能访问：Docker Web 自托管

桌面版只能在本机用；想让手机、浏览器都能访问，就把 Folia 部署成 Web 服务，跑在 NAS 或服务器上。

具体步骤：

1. 按 deploy/docker/README.md 的说明，新建一个空目录，下载compose.yaml和.env模板，不用拉源码。
2. 生成令牌后填进.env的SYNC_TOKEN：

openssl rand -hex 32

3. 启动并等待服务就绪：

docker compose config && docker compose up -d --wait

4. 浏览器访问http://NAS-IP:18080就是 Web 端，http://NAS-IP:13000/health用来检查 Sync Server 是否健康。

环境要求：Docker Engine 24+ 与 Compose v2。💡 还有一个前置条件容易被忽略：读取本地音乐目录依赖浏览器「可信 HTTPS 安全上下文」，局域网 HTTP 下部分能力会降级，NAS 上需要自己配好反向代理和证书。

30 秒验收：确认装好了

三条都打勾，才算真的装完：

• 打开「关于」页，版本号和你下载的文件名一致
• 能登录任一在线音源（网易云 / QQ / 酷狗），或成功导入一个本地音乐文件夹
• 播放一首带歌词的歌，全屏歌词动画渲染正常

避坑：5 个最常见的卡点

• 下载一直中断或慢得没法用→ 官方网盘只覆盖 Windows 和 arm64 Mac → 这两类直接换网盘镜像下载，其余平台继续走 Releases，Arch 用户也可以先手动下好 tar.gz 再本地构建 AUR。
• macOS 弹出「Folia.app 已损坏」→ 应用缺 Apple 签名，被 Gatekeeper 按未公证应用拦截 → 终端执行xattr -dr com.apple.quarantine /Applications/Folia.app后重新打开；macOS 15 起「Control 点击打开」这条绕过路已经走不通，别在上面浪费时间。
• Linux 启动黑屏、透明度异常或闪退→ GPU 与 Electron 图形栈不兼容 → 先试FOLIA_LINUX_GRAPHICS_MODE=swiftshader，不行再换software；X11 下 WebGPU 不可用可加FOLIA_LINUX_VULKAN=1 ./folia-major --ozone-platform=x11，原生 Wayland 不要开 Vulkan。
• 装出来的版本和最新 Release 对不上→ 网盘镜像和 AUR 包都会滞后 → 下载前把文件名里的版本号和 Releases 页最新值比一下，不一致就直接下官方最新包。
• dmg 解压后打不开、安装中途报错→ 多为下载中断导致文件不完整，或跑的是 dmg 挂载盘里的临时副本 → 重新完整下载一次，并确认你运行的是拖进Applications里的那个正式应用。

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