Folia 全屏歌词播放：5 分钟安装指南

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

官方 Releases 页面打开要等好几分钟，发行版软件源里又没有 Folia，第一次安装 Folia 的人大多卡在下载这一步。Folia 是一款以全屏歌词动画为核心的音乐播放器，支持网易云、QQ 音乐、酷狗在线曲库和本地音乐库。这篇指南带你走官方安装包这条路径，从零到打开第一首带歌词的歌，预计 5 分钟。

跑之前先确认环境

• 系统：Windows 10+、macOS 或 Linux x86_64（桌面版是 Electron 应用、内置运行环境，缺了 Node.js 等依赖不会报安装错误）
• 磁盘：2-4 GB 空闲（应用与音频缓存会持续增长，空间不足安装会失败）
• 网络：能访问 GitHub，或有一条国内网盘渠道（Releases 海外下载慢，README.md 里有网盘入口兜底）
• 账号：播放在线歌需要一个网易云、QQ 音乐或酷狗账号（没有账号只能听本地曲库）
• Docker（可选）：仅自托管 Web 版需要，Docker Engine 24+ 与 Compose v2（只用桌面版可跳过这一项）

选一条部署路径

💡 网盘镜像（README 里提到的夸克 / 百度）只同步 Windows 的.exe与 macOS Apple silicon 的.dmg，Linux 读者直接走 AUR 或便携版；网盘版本可能滞后于官方发布。

怎么选：Windows 和 macOS 用户直接选官方安装包，最省心；Arch / Manjaro 用户跑一条 AUR 命令，最省事；其他 Linux 发行版走便携版；想在手机浏览器里听歌再考虑 Docker 部署 Web 版。

⚠️ 只使用 README.md 内的下载入口，不要下载来路不明的第三方转发包。

主路径：桌面版安装步骤

1. 打开 README.md，滚动到「快速下载」一节，有官方 Releases 与网盘镜像两个入口。网络好直接走 Releases，慢就走网盘。
2. 按平台挑文件：Windows 选.exe，macOS 选.dmg，macOS 注意确认 Apple silicon 版本。
3. 下载。一般 3-8 分钟，取决于带宽；如果超过 10 分钟没动，换另一条渠道再下。
4. 双击安装包：Windows 跟着向导走完即可；macOS 把图标拖进 Applications 文件夹。
5. 核对版本：当前官方版本为0.7.23（见 package.json），与安装包文件名比对，网盘版本更旧就先比对再决定是否替换。
6. 从桌面或开始菜单启动 Folia。桌面版内置前后端运行环境，无需额外配置，主界面是 3D 专辑轮播加顶部搜索框。

其他路径一句话入口：

• AUR：执行yay -S folia-major-bin，自动解析alsa-lib、gtk3、nss等依赖，应用落在/opt/folia-major并生成folia-major命令与菜单项，包定义见 packaging/aur/folia-major-bin/PKGBUILD。
• 便携版：从 Releases 下载最新folia-major-<版本>-linux-x64.tar.gz，解压到自选目录即可运行，桌面启动项配置见 packaging/linux/README-LINUX.txt。
• Web 版（Docker）：用 Docker Compose 自托管，Web 默认地址http://NAS-IP:18080，完整步骤见 deploy/docker/README.md。

跑起来之后先放一首歌

1. 在主界面登录入口登录一个在线音乐源。
2. 顶部搜索框搜一首带歌词的歌。
3. 点播放，进入全屏歌词视图，看歌词动画跟随节奏走动。
4. 想听本地歌，进入本地曲库管理导入音频文件，同目录.lrc歌词会自动加载。

验收标准：主界面正在播放歌曲，全屏歌词随节奏逐行动画，部署就算完成。

容易踩的坑

现象：启动后黑屏、透明度/模糊异常或 GPU 进程崩溃→ 处理：用软件渲染启动：

FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major

仍不稳定就改FOLIA_LINUX_GRAPHICS_MODE=software；恢复系统图形路径设为system。

现象：AUR 构建卡在 tar.gz 下载或报 404→ 处理：AUR 包版本落后于官方最新版。先核对版本号，把同版本 tar.gz 预先放进构建源码目录srcdir，再执行makepkg -si跳过慢速下载。

现象：便携版解压后应用菜单里没有启动项→ 处理：依次核对.desktop文件是否在~/.local/share/applications/、__APP_PATH__与__ICON_PATH__两个占位符是否已替换为实际路径、文件是否标记为可信或可执行。

现象：网盘里的版本比预期旧→ 处理：网盘镜像滞后于官方发布属正常现象，以 Releases 页面版本号比对后再决定是否覆盖替换。

接下来可以看

• deploy/docker/README.md：Docker Compose 自托管 Web 版，手机浏览器直接听
• docs/technical.md：技术架构、更新通道与 Wayland / Hyprland 遥控窗细节
• docs/local-library-management.md：本地曲库导入、重扫与歌词匹配细则

把歌词动画拉满，切一首你最近循环的歌。

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