Folia 安装教程：零门槛到歌词动画播放器跑起来
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia 是一款把歌词渲染成全屏动画的歌词动画播放器，音源覆盖网易云、酷狗、QQ 音乐、Navidrome 与本地曲库。本文带你在 Windows、macOS、Linux、Web 四条路径上完成下载、安装到播放第一首歌。
装之前先过一遍
做完这节，你手上多了一张对照表，缺什么一目了然。
| 检查项 | 要求 | 备注 |
|---|---|---|
| 系统 | Windows 10/11、macOS（Intel 与 Apple silicon）、Linux x86_64 | 桌面端三平台均有安装包 |
| 网络 | 能打开 GitHub Releases 页 | 国内直连慢可走 README 里的网盘镜像 |
| 依赖 | 桌面版无需预装，运行环境已内置 | Arch 走 AUR 需先装 yay 或 paru；Web 版需 Docker |
| 磁盘 | 预留约 500MB | 安装路径避免中文与空格 |
Windows 安装包安装与首次启动验证
做完这节，开始菜单里多了一个 Folia 条目。
操作：打开仓库 README 的「快速下载」一节，进 Releases 页取最新.exe，双击按向导装完。
包名里的版本段要和你选的 Release 对得上，对不上说明拿到的是旧包。国内网络慢就换 README 里的网盘镜像，网盘只有 Windows 与 Apple silicon 的最新版。
验证：开始菜单找到 Folia，点开能看到首页，顶部可切换音源，底部是播放条。
安装后点不开，多半是路径带中文或空格，重装到纯英文目录。
macOS .dmg 安装与首次启动放行
做完这节，Applications 里多了一个 Folia。
操作：双击.dmg，把 Folia 图标拖进 Applications，弹出光盘。首次启动被拦时，到「系统设置 → 隐私与安全性」放行一次。
提示「无法验证开发者」时，右键图标选「打开」再放行。
验证：从 Applications 启动后出现 Folia 首页，即算安装成功。
网盘镜像只有 Apple silicon 包，Intel Mac 回 Releases 页取对应 Intel 包。
Linux 便携版部署与桌面启动项配置
做完这节，你的应用菜单里多了一个 Folia，终端里folia-major可直接执行。
操作：Debian / Ubuntu 取.deb，Fedora 取.rpm，其他发行版取linux-x64的tar.gz便携包，解压到固定目录：
mkdir -p ~/Apps/Folia && tar -xzf folia-major-0.7.23-linux-x64.tar.gz -C ~/Apps/Folia # 解压便携包复制桌面启动项模板，再把__APP_PATH__与__ICON_PATH__替换为可执行文件和图标的绝对路径：
cp ~/Apps/Folia/resources/linux/folia-major.desktop ~/.local/share/applications/ # 复制启动项模板Arch 系一条命令搞定，paru 用户换成 paru：
yay -S folia-major-bin # AUR 一键安装验证：终端敲folia-major能直接跑，或应用菜单出现 Folia 条目。
启动后黑屏、透明度或模糊异常，用
FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major再跑一次。 swiftshader 下仍闪或崩，换最保守的软件渲染：FOLIA_LINUX_GRAPHICS_MODE=software ./folia-major。 快捷方式点了没反应，检查.desktop的 Exec 与 Icon 是否填了绝对路径，并按桌面要求标记为可信。
Web 版 Docker Compose 全栈部署
做完这节，你手上多了一个http://本机IP:18080可访问的 Web 入口。
操作：从仓库deploy/docker/目录取compose.yaml与.env.example，放进同一个空目录，把后者改名为.env，给SYNC_TOKEN填一段随机串。然后验证并启动：
docker compose config && docker compose up -d --wait # 校验配置并拉起全部服务验证：浏览器打开http://<你的IP>:18080看到 Folia 首页；Sync Server 在 13000 端口的/health有响应。
起不来先看
docker compose ps输出，确认.env里FOLIA_IMAGE_NAMESPACE有值。 本地音乐库访问依赖可信 HTTPS 上下文，NAS 部署需配反向代理与证书。
跑起来了吗？
- 启动后出现首页，顶部能切换在线音源，底部有播放控制条
- 登录网易云等音源后，歌曲列表加载出来且能正常播放
- 放一首带歌词的歌，全屏歌词动画跑起来
- （Linux）终端里
folia-major可直接执行
高频卡点
Q：各平台的安装包去哪找？A：Releases 页有 Windows、macOS、Linux 最新正式版。网盘镜像只提供 Windows 与 Apple silicon 两个包。
Q：下载卡住不动怎么办？A：切到 README「快速下载」的夸克或百度网盘镜像。网盘里没有你的平台，就回 Releases 取正式包。
Q：Linux 启动后黑屏？A：先用FOLIA_LINUX_GRAPHICS_MODE=swiftshader启动试一次。还不行换software，那是最保守的路径。
Q：Wayland 下能用吗？A：桌面端支持 Wayland，壁纸模式另需合成器实现wlr-layer-shell，GNOME 不支持。
Q：Folia 会动我本地文件吗？A：它只读取音频元数据、同目录同名.lrc歌词与封面，不上传文件内容。
延伸阅读
- docs/technical.md：Linux 图形模式、Wayland 遥控窗与部署环境变量等桌面端细节。
- packaging/linux/README-LINUX.txt：便携目录结构、桌面启动项与图形变量逐项说明。
- deploy/docker/README.md：Web 版 Docker Compose 全栈部署与环境变量清单。
- docs/local-library-management.md：本地曲库导入、重扫、在线匹配与故障排查。
挑好包，放首歌，看歌词点亮整块屏 🎵
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
