Folia 安装完整教程：十分钟在三台设备跑起全屏歌词动画播放器

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

Folia 是一款基于 Electron 的全屏歌词动画播放器，能播放本地曲库、Navidrome，以及网易云音乐、QQ 音乐、酷狗等在线音源。跟着这份 Folia 安装教程走一遍，十分钟内你就能看到带歌词动效的主界面。

动手之前：一眼对上你的 Folia 下载包

⚠️ 包只从官方入口拿：网盘镜像只收录 Windows 与 Apple silicon 的正式版，Linux 不在网盘里，要去 Releases 列表下载。

安装：Windows、macOS、Linux 三条路

Windows 三步装好 Folia

1. 打开 README.md，在「快速下载」小节复制官方网盘链接（夸克或百度均可）。 → 拿到下载入口；用百度盘时提取码是flia。先把文件转存到自己的网盘再下载，中途断流也能续传。
2. 双击Folia-Setup-<版本>.exe，按默认路径一路装完。 → 开始菜单里出现「Folia」图标。
3. 从开始菜单启动 Folia。 → 主窗口弹出：顶部是搜索栏，中间是专辑卡片墙；点任意一首歌即可播放，并看到全屏歌词动画。桌面版内置前后端运行环境，不用再装任何依赖。

macOS 拖进「应用程序」就算装完

1. 同样从 README.md「快速下载」小节复制网盘链接，转存后下载。 → 拿到 macOS 的安装包。
2. 取Folia-<版本>-arm64.dmg文件。 → 下载完成，双击打开。
3. 把 Folia 图标拖进「应用程序」文件夹。 → Launchpad 里出现 Folia。
4. 首次启动若提示已损坏或被拦截，右键 Folia 图标选择「打开」。 → 细节见 docs/desktop/macos-app-damaged.md。启动后能看到带歌词动画的主界面。

Linux 装 Folia：便携版解压与 AUR 构建

便携版：解压后一条命令启动

1. 到仓库 Releases 列表下载folia-major-<版本>-linux-x64.tar.gz。 → 版本号与网盘镜像保持一致。
2. 放到不会被清理的固定目录，解压。 → 得到含folia-major可执行文件与resources/目录的目录。
3. 直接启动：

   ./folia-major

   → 终端弹出带搜索栏与专辑卡片的主窗口。

4. 想要桌面启动项，复制包内模板：

   cp resources/linux/folia-major.desktop ~/.local/share/applications/

   → 再把文件里的__APP_PATH__与__ICON_PATH__两个占位符替换为真实绝对路径，完整示例见 packaging/linux/README-LINUX.txt；桌面环境有要求时记得把该.desktop文件标记为可信。

AUR 构建（Arch Linux）

1. 没有 AUR Helper 先装一个，yay 或 paru 都行。 → 终端里能直接调用yay或paru。
2. 执行构建安装：

   yay -S folia-major-bin

   →alsa-lib、gtk3、libxss、nss会自动装好。

3. 卡在拉取 tar.gz 时，先把同版本文件放进构建目录的源码目录，再继续构建：

   makepkg -si

4. 用包管理器核对结果：

   pacman -Qs folia-major

   → 输出里出现folia-major-bin条目。构建逻辑见 packaging/aur/folia-major-bin/PKGBUILD。

首次启动与验收：三条信号任选其一

• ✅ 主窗口能打开，看得到搜索栏与专辑卡片，播放歌曲时有全屏歌词动画。
• ✅ 便携版目录下运行./folia-major，能弹出带歌词的主窗口。
• ✅ Arch 上pacman -Qs folia-major输出里有folia-major-bin条目。

卡住了怎么办：Linux 黑屏、Folia 打不开这样修

• 黑屏、透明度或模糊异常、GPU 崩溃（Linux）：先切 swiftshader 软件渲染

  FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major

• swiftshader 仍不稳：换最保守的纯软件渲染

  FOLIA_LINUX_GRAPHICS_MODE=software ./folia-major

  稳定后用FOLIA_LINUX_GRAPHICS_MODE=system切回系统图形路径。

• 便携版起不来：检查folia-major可执行文件和resources/目录是否还在同一个便携包目录里，缺一个都启动不了。
• Mac 提示「应用已损坏」：右键图标选「打开」，或按 docs/desktop/macos-app-damaged.md 处理。

⚠️ 图形模式变量只影响 Electron 的 Linux 启动参数，不改 Web 端与同步服务配置。

接下来马上做：把 Folia 接到真实曲库

• 接本地音乐：导入本地文件夹，自动读取元数据、同目录歌词与封面，见 docs/local-library-management.md。
• 接 Navidrome 与在线音源：在「设置 → 连接与集成」填服务器地址；网易云、QQ 音乐、酷狗可直接接，能力一览见 README.md「核心能力」。
• 开壁纸模式：在「选项 → 桌面端」开启「壁纸模式」，主窗口沉到所有窗口之下当桌面歌词壁纸，说明见 docs/wallpaper-mode.md。
• 装模组：在「设置 → 模组 → 模组系统」开启后，把模组 zip 拖进面板即可安装，规范与示范见 mods/README.md。

• 自托管 Web 版：用 Docker Compose 全栈部署，见 deploy/docker/README.md。

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