Folia 歌词动画音乐播放器快速安装指南：桌面与 NAS 全流程

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

Folia 是一款把歌词渲染成全屏沉浸式动画的音乐播放器，可接入网易云、QQ 音乐、酷狗、Navidrome 与本地曲库。本文按机器类型给出 4 套安装方案：Windows 与 macOS 桌面 3 步、Arch 一条命令、其他 Linux 便携版 3 步、NAS 上 Docker 自托管 4 步，全程不超过 30 分钟。

两问定位你的路线

动手前先回答两个问题，就能锁定唯一该走的方案：

1. 这台机器有屏幕、当桌面用，还是无头的服务器 / NAS？——前者装桌面版，后者走 Docker 自托管。
2. 你的 Linux 发行版是 Arch 吗？——是，AUR 一条命令装完；不是，解压便携版后手动补启动项。

各方案依赖的运行环境已并入下方对应小节的「① 你需要」，不需要预先统一备货。

Arch 一条命令装 folia-major-bin

① 你需要

• 配好的 AUR Helper（yay 或 paru）
• 能访问 GitHub Releases 的网络，构建时要拉取预构建包

② 操作步骤

1. 安装 AUR 包（yay 与 paru 二选一，版本同步由 packaging/aur/folia-major-bin/update.sh 维护）：

   yay -S folia-major-bin # paru 用户替换成 paru -S folia-major-bin

2. 构建完成后程序落盘到/opt/folia-major，桌面启动项自动注册，无需再配。

③ 如何判断成功

• 终端直接运行folia-major能拉起主界面，应用菜单出现 folia-major 图标。
• 播放任意一首歌，歌词渲染为全屏动画，窗口随歌曲切换主题。

⚡ AUR 构建需要下载folia-major-<版本>-linux-x64.tar.gz，网速慢时先把同版本压缩包经网盘转存，放进构建源码目录再手动执行makepkg -si跳过下载。alsa-lib、gtk3、libxss、nss 四个运行依赖由 AUR Helper 构建时自动装好，打包逻辑见 packaging/aur/folia-major-bin/PKGBUILD。

Windows 与 macOS：网盘直装桌面版

① 你需要

• 夸克或百度客户端账号
• 官方入口：README.md「快速下载」小节（夸克网盘或百度云，提取码flia）
• 导入本地音乐时，曲库目录需可写

② 操作步骤

1. 打开 README.md「快速下载」小节，复制官方网盘链接（夸克网盘或百度云，提取码flia）。⚠️ 第三方转发包可能夹带旧版本或篡改内容，只认官方入口。
2. 登录夸克或百度客户端，把安装包转存到自己的网盘，再下载到本地。
3. 运行安装包：Windows 为.exe，macOS 为.dmg（Apple silicon 选对应版本），装完直接启动。

③ 如何判断成功

• 开始菜单 / 应用菜单出现 folia-major 启动项，点它能打开主界面。
• 播放任意一首歌，歌词渲染成全屏沉浸式动画，窗口主题随歌曲切换。
• 网易云、QQ 音乐、酷狗、Navidrome 与本地曲库各登录 / 导入成功一次，来回切换不报错。
• 导入目录里的歌曲自动读取了元数据与同名.lrc歌词。

其他 Linux：便携版三步补齐启动项

适合 Ubuntu、Debian、Fedora 等发行版。Linux 便携版解压后包含folia-major可执行文件、resources/linux/icon.png图标与resources/linux/folia-major.desktop启动项模板，完整说明见 packaging/linux/README-LINUX.txt。

① 你需要

• Linux 便携版压缩包
• 解压权限，以及写~/.local/share/applications/的权限

② 操作步骤

1. 解压到固定目录，先手动跑一遍确认可执行：

   ./folia-major # 确认可执行文件与 resources/ 同目录

2. 把启动项模板复制进用户应用目录：

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

3. 编辑复制出的folia-major.desktop：__APP_PATH__替换为folia-major可执行文件的绝对路径，__ICON_PATH__替换为resources/linux/icon.png的绝对路径；桌面环境若有要求，再将该.desktop标记为可信。

③ 如何判断成功

• 应用菜单出现 folia-major 图标，点击可正常拉起主界面。
• 播放任意一首歌，全屏歌词动画正常渲染、窗口随歌曲切换主题。

NAS 上 Docker 安装 Web 版

适合无桌面环境的 NAS 或服务器，完整部署文档见 deploy/docker/README.md。对外的端口只有两个：Web 网关默认 18080，Sync Server 默认 13000。

① 你需要

• Docker Engine 24+ 与 Docker Compose v2
• 网易云、QQ 音乐、酷狗至少一个账号；Navidrome 需要自己的服务器地址

② 操作步骤

1. 新建空目录，只取 Compose 与环境变量模板两个文件（模板即 deploy/docker/.env.example）：

   mkdir folia-docker && cd folia-dockercurl -fL https://raw.githubusercontent.com/chthollyphile/folia-major/main/deploy/docker/compose.yaml -o compose.yamlcurl -fL https://raw.githubusercontent.com/chthollyphile/folia-major/main/deploy/docker/.env.example -o .env

2. 生成同步令牌，把输出填入.env的SYNC_TOKEN（至少 8 位）：

   openssl rand -hex 32

3. 验证配置并启动容器：

   docker compose config && docker compose pull && docker compose up -d --wait

4. 浏览器访问http://NAS-IP:18080打开 Folia Web。

③ 如何判断成功

• docker compose ps显示全部容器 running。
• 浏览器打开http://NAS-IP:18080能看到首页。
• http://NAS-IP:13000/health返回健康，.env中SYNC_TOKEN已生效。

出错了怎么办

• 现象：Linux 启动后黑屏、透明度 / 模糊异常或 GPU 崩溃可能原因：系统图形栈与渲染路径不兼容处理：改用软件渲染模式启动，更多取值见 packaging/linux/README-LINUX.txt：FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major，仍不稳定再换FOLIA_LINUX_GRAPHICS_MODE=software ./folia-major

• 现象：网盘链接失效或版本太旧可能原因：使用了非官方渠道的转存处理：以 README.md「快速下载」小节的官方入口为准，再回 Releases 页面核对版本号。

• 现象：GitHub Releases 下载慢甚至断流可能原因：当前网络访问海外 CDN 受阻处理：Windows 与 Apple silicon 改走官方网盘；Arch 用户先把同版本folia-major-<版本>-linux-x64.tar.gz经网盘转存，放进构建源码目录再makepkg -si。

• 现象：装完桌面版，应用菜单里没有启动项可能原因：.desktop内路径写错，或文件未标记可信处理：检查~/.local/share/applications/folia-major.desktop的路径是否与实际文件位置一致，并按桌面环境要求把该文件标记为可信或可执行。

按机器对号入座：桌面走网盘或 AUR，无头设备走 Docker，30 分钟内全部完成。桌面端细节、Wayland 与遥控窗口见 docs/technical.md；Linux 渲染模式的更多取值见 packaging/linux/README-LINUX.txt。

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