Folia 安装指南：从选包到首次放歌的完整流程

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

Folia 是一款全屏沉浸式歌词动画播放器，把网易云、酷狗、QQ 音乐、Navidrome 和本地音乐库里的歌渲染成铺满整个窗口的歌词动画。桌面版基于 Electron 打包，安装即用，覆盖 Windows、macOS 和 Linux。Folia 下载的关键是先选对包：不同系统对应不同文件后缀，走官方 Releases 还是网盘镜像，则取决于你的网络环境。

先用三个问题定位自己

1. 系统与架构是哪种？它决定该拿的文件后缀：Windows 是.exe；Mac 在 M1 及以后芯片上是 Apple silicon（arm64），老机型是 Intel（x64）；通用 Linux 一律是 x64。看一眼系统信息面板即可确认。
2. GitHub 直连顺不顺？试着打开一下官方 Releases 页：能秒开、下载不卡顿，就走直连；转圈、超时，就换国内网盘镜像（镜像只覆盖 Windows 与 Apple silicon）。
3. 曲库在哪？本地文件、自建 Navidrome，还是网易云、QQ 音乐这类内置平台——选包方式完全相同，但它决定装完之后要在「设置」里配置哪个音源。手机端或浏览器里使用需要另行部署 Web 版，与桌面版是两条版本线，本文流程面向桌面版。

按路线走，一条路线一个闭环

路线一：Windows 与 Apple silicon Mac——网盘镜像优先，Releases 兜底

1. 选渠道。GitHub 直连顺畅就打开官方 Releases 页取最新版；否则打开 README 的「快速下载」一节，走官方网盘镜像，Windows 拿.exe，Apple silicon Mac 拿-arm64.dmg（百度云提取码flia）。
2. 核对版本号。与最新 release 对比，落差太大就换直连渠道，别装旧版。
3. 安装。Windows 双击.exe按向导装完；macOS 在 dmg 窗口里把Folia.app拖进「应用程序」，不要在挂载盘里直接运行。
4. 启动。从开始菜单或启动台打开 Folia，直接进入验收。

⚠️ 网盘镜像只有 Windows 和 Apple silicon 两个正式版安装包，Intel Mac 与所有 Linux 都不在其中，别在网盘里翻找。

路线二：Intel Mac 与其他 Linux——Releases 直连

1. 拿包。打开官方 Releases 页：macOS Intel 拿Folia-<版本>-x64.dmg，Linux 拿folia-major-<版本>-linux-x64.tar.gz。这两个环境只有这一条渠道。
2. macOS 按路线一步骤 3 安装即可；Linux 没有安装环节，解压到固定目录（例如~/Apps/Folia/），以后升级也覆盖到这里。
3. Linux 创建桌面启动项：把包内resources/linux/folia-major.desktop复制到~/.local/share/applications/，打开复制出来的文件，将__APP_PATH__、__ICON_PATH__两个占位符替换为可执行文件和图标的实际绝对路径，模板示例见 Linux 便携版说明。
4. 启动。在解压目录运行./folia-major，或从应用菜单点击 Folia。

⚠️ 解压目录日后移动或删除时，.desktop 文件里的路径要同步重改，否则菜单快捷方式找不到程序。

路线三：Arch 系——包管理器一条命令装好

1. 确认yay或paru可用，执行yay -S folia-major-bin。
2. AUR 包会自动从 Releases 拉取 Linux 包，安装到/opt/folia-major、创建桌面启动项，并一并装好 alsa-lib、gtk3、libxss、nss 等运行依赖。
3. 应用菜单里直接启动即可。

⚠️ AUR 包本质仍是从 Releases 下载 tar.gz，卡在下载等于直连失败，改走路线二手动部署；当前 PKGBUILD 版本为 0.1.4，可能落后于 Releases 最新版，在意版本号就自己拿便携包。

装完，用一张清单验收

逐项打勾，三项全部通过才算装对：

• 打开应用，首页正常渲染：搜索框、专辑卡片都出来了
• 搜索一首熟悉的歌，点击播放不出错
• 歌词以动画形式铺满全屏——这是 Folia 的核心效果

验收通过后的日常：导入本地歌曲时会自动匹配在线歌词与封面，网易云、QQ 音乐、Navidrome 等在线音源都能在「设置」里接入。

出问题，先诊断再动手

动手前先问三个问题定位问题：

1. 哪个平台？Linux 黑屏与 macOS「应用已损坏」的解法完全不同，先别串台。
2. 打不开，还是图形异常？这能区分签名/权限类问题与图形驱动类问题。
3. 卡在下载，还是卡在启动？下载卡住是网络问题，启动异常是系统问题，两件事不要混着查。

再对症下药：

• Folia 黑屏、透明度/模糊异常、GPU 崩溃（Linux）：用FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major启动，强制内置软件光栅化；仍不稳定就换更保守的FOLIA_LINUX_GRAPHICS_MODE=software ./folia-major。
• macOS 提示「Folia.app 已损坏，无法打开」：按住 Control 点应用选「打开」，或到「隐私与安全性」点「仍要打开」；最后手段执行xattr -dr com.apple.quarantine /Applications/Folia.app移除下载隔离标记。
• 网盘镜像链接失效或版本太旧：以 README「快速下载」一节的最新链接为准，再不行回 Releases 直连。
• Linux 版想升级：桌面 Linux 版没有自动更新，下载新版 tar.gz 重新解压覆盖原目录即可，桌面启动项通常不用动。

接下来

• 本地音乐库管理：导入本地歌曲后的重扫、匹配与实体管理细节
• 技术说明：Wayland 壁纸模式、遥控窗等平台细节
• macOS「应用已损坏」完整排查：含 Gatekeeper 原理与全部处理路径

想自建曲库托管，deploy/docker/README.md 里还有 Docker 全栈部署方案。装好放歌吧 🎵

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