Folia 下载与安装教程：十分钟把全屏歌词动画播放器跑起来
项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major Folia 把歌词渲染成全屏沉浸式动画，支持本地音乐、Navidrome 与网易云、QQ 音乐、酷狗等在线音源。这篇 Folia 安装教程帮你把它装到 Windows、macOS 或 Linux 并成功播放，顺利的话十分钟就能跑起来。
动手前自检
先勾一遍，判断你走哪条路线：
- 系统属于 Windows / macOS / Linux 之一，且清楚自己是 Apple silicon 还是 Intel
- 国内网络优先网盘，国外网络走官方直连
- 是否接受命令行：纯图形安装不需要，Linux 与 Arch 路线需要
- Arch 系已装好 yay 或 paru 助手
路线速选
| 你的环境 | 推荐路线 | 预期耗时 | 是否需要终端 |
|---|---|---|---|
| Windows | 官方网盘 → .exe | 5–10 分钟 | 否 |
| Apple silicon macOS | 官方网盘 → .dmg | 5–10 分钟 | 否 |
| Intel macOS | 官方 Releases → .dmg | 10–20 分钟 | 否 |
| Arch / EndeavourOS | AUR 一行命令 | 3–5 分钟 | 是 |
| 其他 Linux | 便携版 tar.gz 解压 | 5–10 分钟 | 是 |
| NAS / 服务器 | Web 版自托管 | 30 分钟以上 | 是 |
网盘镜像只覆盖 Windows 与 Apple silicon 的正式版，Linux 包和 Intel Mac 请直接走官方 Releases。
网盘镜像装 Windows 与 Apple silicon 版
- 打开 README.md 的「快速下载」一节，点官方网盘入口。
- 在网盘客户端先转存到自己网盘再下载，中途断了可续传。
- 选对应安装包：Windows 选
.exe，macOS 选.dmg。 - 运行安装程序按向导走完；桌面版已内置前后端环境，装完直接能用。
⚠️ 只用 README 里的官方网盘入口，避免来路不明的转发包。
直连官方 Releases 装 Intel Mac
- 进 Folia 的 Releases 页面，下载 Intel 版
.dmg。 - 双击挂载，把 Folia 拖进 Applications 即完成。
💡 国外网络直连更稳；国内慢就回到网盘路线，但网盘没有 Intel Mac 包。
AUR 一行命令装 Arch 系
- 确认已安装 AUR 助手（yay 或 paru）。
- 终端执行下面命令，把
yay换成paru也一样：
yay -S folia-major-bin
- 构建会自动解决 alsa-lib、gtk3、nss 依赖，把程序装进
/opt/folia-major并生成应用菜单项。
依赖与安装位置定义在 PKGBUILD。
⚡ 构建要从 Releases 拉 Linux 压缩包，慢的话先手动下载同版本压缩包放进源码目录，再执行
makepkg -si。
便携版解压装其他 Linux
- 从 Releases 下载
folia-major-<版本>-linux-x64.tar.gz。 - 解压到任意目录，包里含
folia-major可执行文件、图标与桌面模板。 - 终端运行确认能启动：
./folia-major
- 想加桌面入口：把
resources/linux/folia-major.desktop复制到~/.local/share/applications/，替换__APP_PATH__、__ICON_PATH__占位符为实际路径，细节见 README-LINUX.txt。
Web 版自托管（NAS / 服务器）
适合想让手机浏览器访问的场景。Docker 路线见 deploy/docker/README.md：拉取 Compose 与环境模板、生成 Sync Token 后 docker compose up 即可。这条路线耗时最长，首次部署建议单独留出一段时间。
装完验收
- 启动：从应用菜单或快捷方式打开 Folia。
- 核对：进「关于」或首页，版本号应为 0.7.20。
- 触发核心功能：登录一个在线音源或导入本地曲库，播放一首带歌词的歌，进入全屏歌词动画。
踩坑速查
| 现象 | 常见原因 | 解决操作 / 命令 |
|---|---|---|
| 下载中断或很慢 | 国内访问 Releases 受限 | 改走官方网盘；Linux 包先手动下载再本地构建 |
| Linux 启动黑屏、透明度异常或闪退 | GPU 兼容问题 | FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major，仍不稳改用 software |
| 网盘版本偏旧 | 镜像滞后于最新发行 | 比对文件名版本，不一致就等同步或改直连 |
| 便携版解压后无桌面入口 | 未生成启动项 | 复制 .desktop 模板到 applications 并替换占位符 |
导入本地音乐或登录在线音源后，第一首歌就能让全屏歌词亮起来。
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/gitblog_00266/article/details/166102718
