Folia 完整安装部署指南：从零跑通全屏歌词动画
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia 全屏歌词动画播放器，支持网易云、QQ 音乐、酷狗、Navidrome 与本地音乐库。本文给出本机开箱、Linux 便携部署、Docker 自托管三条安装路线，跟着做完能放出第一首歌。
最短路：四步看到歌词动画
- 打开 README.md，定位「快速下载」一节，按平台取安装包——Windows 拿
.exe，macOS 拿.dmg——装上。 - 启动 Folia，无需任何配置。
- 首页搜音源名登录账号；或者不登账号，直接打开本地音乐库，导入一个音频目录。
- 播放任意歌曲，确认歌词以全屏动画渲染出来，即算跑通。
提前说：网盘镜像只覆盖 Windows 与 Apple silicon 两个正式版安装包，找不到你平台的包就跳去对应部署形态一节，别在网盘里翻。
上面四步只适用 Windows 与 macOS。Linux 桌面与 NAS 上的 Web 版是另外两条路，形态不同，解法也不同。
本机开箱：Windows 与 macOS 官方版下载与安装
Windows 取.exe安装包，macOS 取.dmg镜像，M 系芯片选 Apple silicon 版本，双击运行即可。
下载前先在 README 的「快速下载」一节核对版本号：网盘版本可能落后于最新 Releases，装到旧版会白白浪费一轮排查时间。Intel Mac 的包不在网盘里，直接去仓库 Releases 页面取便携包，路线和 Linux 一致。
Linux 便携部署：AUR 一条命令或手动桌面项
Windows 和 macOS 靠安装包一步到位，Linux 没有统一安装包，得先定交付形态：Arch 用 AUR 现成包，其余发行版走「解压 + 配桌面项」。
Arch 捷径：AUR 一条命令
确认装好yay或paru，执行yay -S folia-major-bin。助手会自动带上alsa-lib、gtk3、libxss、nss依赖，把 Folia 部署到/opt/folia-major。构建脚本在 packaging/aur/folia-major-bin/，本质是从 Releases 拉linux-x64.tar.gz重新打包——你的网络连 Releases 慢时，构建会卡在下载步骤，这时直接切到手动部署，自己控制下载进度。
其余发行版：解压加配桌面项
- 从仓库 Releases 页面取
linux-x64.tar.gz，解压到固定目录，如~/Apps/Folia/，别放临时目录。 - 把包内
resources/linux/folia-major.desktop复制到~/.local/share/applications/。 - 打开复制出的文件，把
__APP_PATH__与__ICON_PATH__两处占位符替换为绝对路径。 - 从应用菜单启动
folia-major，桌面项即生效。
每一步的完整示例见 packaging/linux/README-LINUX.txt，照着对一遍路径就不会错。
三条本机路线到此结束。想让手机浏览器直接打开 Folia，就换容器化自托管这条交付形态。
Docker 一键部署 Web 自托管版到 NAS
部署不需要源码，只要两个文件：新建空目录，从仓库 deploy/docker/ 取compose.yaml和.env模板（.env.example，取回后改名.env）放进去。
openssl rand -hex 32 # 输出填入 .env 的 SYNC_TOKEN，必填 docker compose up -d启动后浏览器访问http://<NAS 地址>:18080进入 Folia Web 版。各环境变量含义、端口分配、Navidrome 预置账号怎么配，deploy/docker/README.md 有完整清单，对着自己的网络环境逐项确认。别把SYNC_TOKEN留空，同步服务不会启动；AI 配置可以留空，不影响放歌。
容器栈起来后，用浏览器放出第一首歌，验证整条链路是否真的工作。
装完自检：放一首歌验证 ✅
桌面版与 Web 版验证方式一致，逐项勾选：
- 应用正常打开，无黑屏，界面渲染完整
- 在线音源登录成功，或本地音频目录导入成功
- 任意歌曲播放，歌词以全屏动画渲染
- 同名
.lrc/.vtt歌词文件被自动识别 - 本地歌曲的封面与歌词自动在线补全
五项全勾即安装完成。Folia 的核心卖点正是多套歌词动画主题加按歌曲 AI 生成配色背景，放歌时顺手切几个主题，看看差异。
自检不通过时，症状多半集中在这两处：Linux 图形链路与下载源。两个高频卡点各配一行处理，直接查表。
高频卡点速查：Linux 黑屏与构建卡住
| 现象 | 一行处理 |
|---|---|
| Linux 启动后黑屏、模糊或透明度异常 | FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major |
| 软件光栅化后仍不稳定 | 换最保守的FOLIA_LINUX_GRAPHICS_MODE=software ./folia-major |
| AUR 构建卡在下载步骤 | 跳过构建，改走手动便携包部署路线 |
提前说：排查时先确认可执行文件与resources/位于同一便携包目录，拆开来会出各种怪问题。这些变量只影响 Linux 桌面端启动参数，不改 Web 版或同步服务配置。Wayland 壁纸模式、遥控窗等更深机制，去 docs/technical.md 里挖。
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
