Folia 安装与快速上手：10 分钟把全屏歌词播放器装进桌面或 NAS

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

Folia 是一个把歌词渲染成全屏动画的开源音乐播放器，能接网易云、QQ 音乐、酷狗、Navidrome 和本地曲库。本文带你完成 Folia 安装：桌面安装包、Linux 手动部署、Arch 一行命令、Docker 多设备部署四种方式，每种都带步骤和启动确认。全程大约 10 到 15 分钟。

选装法：四种安装方式对比

动手前的 5 项准备

• CPU 架构：Apple silicon 的 Mac 拿 arm64 包，Intel Mac 拿 x64 包，拿错架构装不上。
• 网络：能直连 GitHub Releases 就走直连；下载慢时，Windows 与 Apple silicon 的正式版可以走 README「快速下载」一节的夸克与百度网盘镜像（百度提取码flia），镜像可能比最新 release 落后，下完先对一眼版本号。
• 磁盘：桌面端解压后的目录留 1 GB 以上余量。
• Linux 两条：便携包必须保留resources/目录与可执行文件同目录，别只拷folia-major单个文件；走 AUR 的机器需要yay或paru其中之一。
• Docker 一条：确认docker compose version是 v2，且机器上有openssl可生成令牌。

Windows 与 macOS 桌面安装包安装

1. 打开项目 Releases 页面，下载最新版（当前正式版0.7.23，以 Releases 页面为准）。
2. Windows：下载.exe安装包，双击运行，向导一路「下一步」完成。
3. macOS：按芯片下载 arm64 或 x64 的.dmg，把 Folia 拖进Applications。Linux 桌面用户直接看下一节。
4. ✅ 启动确认：
   • 窗口标题栏出现Folia字样，右下角出现播放球
   • 搜一首带逐字歌词的歌，出声且全屏动画正常出字
   • 「帮助」里的版本更新（Release Notes）弹窗显示当前版本号，应与下载的一致

macOS 首次打开若弹「应用已损坏」或「无法验证」，是未做 Apple Developer ID 签名导致的隔离属性拦截，修复命令在下方排障一节。

Linux 手动部署步骤

1. 从 Releases 取linux-x64.tar.gz（Debian 系也可直接取.deb，Fedora 系取.rpm），解压到任意目录。
2. 确认三件套在同一目录：folia-major可执行文件、resources/linux/icon.png、resources/linux/folia-major.desktop。缺了resources/会丢图标和启动项。
3. 终端运行./folia-major，先确认能启动。
4. 想进应用菜单，把桌面项模板复制到~/.local/share/applications/folia-major.desktop。
5. 打开复制出来的文件，把__APP_PATH__、__ICON_PATH__两个占位符分别替换为可执行文件和图标的绝对路径，完整示例见 packaging/linux/README-LINUX.txt。
6. 桌面环境有要求的话，给这个.desktop文件标记为可信。
7. ✅ 启动确认：应用菜单出现 Folia 且图标正常；终端再跑一次./folia-major，主窗口照常弹出。

Arch 一行命令安装

1. 确认 AUR helper 可用：yay --version。用paru就把下面命令里的yay换成paru。
2. 执行yay -S folia-major-bin，等构建完成。
3. 构建过程会拉取 release 的linux-x64包，解到/opt/folia-major，并在/usr/bin建立folia-major链接。
4. 该包声明的依赖是alsa-lib、gtk3、libxss、nss，可打开 PKGBUILD 逐条核对。
5. ✅ 启动确认：应用菜单出现 Folia 入口；终端敲folia-major能弹出主窗口。

构建长时间停在下载步骤，说明是国内直连 GitHub 慢，转上一节的 Linux 手动部署即可。

Docker 多设备部署 Web 版

适合手机、电视、NAS 等浏览器访问的场景。要求 Docker Engine 24+ 与 Docker Compose v2，部署不需要 clone 源码：

1. 建目录：mkdir folia-docker && cd folia-docker。
2. 从仓库 deploy/docker/ 目录取compose.yaml与.env.example两个文件放入当前目录，并把.env.example重命名为.env。
3. 生成同步令牌：openssl rand -hex 32，把输出写入.env的SYNC_TOKEN（至少八位）。AI 配置留空不影响播放。
4. 校验并启动：

docker compose config docker compose up -d --wait docker compose ps

5. ✅ 启动确认：
   • 浏览器访问http://NAS-IP:18080出页面
   • http://NAS-IP:13000/health返回健康检查通过
   • docker compose ps里所有容器状态为 running

网易云、酷狗、QQ 音乐 API 都收在 gateway 后面，不单独暴露宿主机端口，环境变量与回滚细节见 deploy/docker/README.md。

安装排障速查

启动报错时，桌面端日志在「设置 → 开发者」面板里读；勾上「Save to file」会落盘到应用数据目录的logs/runtime/，这是第一现场。

• macOS 弹「应用已损坏」或「无法验证」→ 当前 macOS 版未做 Apple Developer ID 签名，浏览器下载带上了隔离属性 → 终端执行xattr -dr com.apple.quarantine /Applications/Folia.app后从Applications重新打开。macOS 版暂不支持应用内自动更新，每次覆盖安装后要再跑一次这条命令。
• Linux 启动黑屏、透明度或模糊异常→ GPU 渲染路径在当前显卡上不稳 → 先FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major；仍闪再用最保守的FOLIA_LINUX_GRAPHICS_MODE=software ./folia-major。排查前确认可执行文件和resources/还在同一个便携包目录。
• X11 下提示没有可用的 WebGPU→ Electron 默认关闭了 Vulkan → 执行FOLIA_LINUX_VULKAN=1 ./folia-major --ozone-platform=x11。仅 X11 / XWayland 生效，原生 Wayland 下该变量会被忽略，开了反而会让 GPU 进程崩溃。
• Arch 构建长时间停在下载→ 国内直连 GitHub Releases 慢 → 改用 Linux 手动部署一节的 tar.gz 流程。
• 网盘里找不到 Intel Mac 或 Linux 的包→ 网盘镜像只覆盖 Windows 与 Apple silicon → 回 Releases 页面取对应平台的文件。

相关文档

• docs/technical.md：Linux 包细节、Wayland 壁纸模式、遥控窗——调桌面端进阶行为时看它。
• deploy/docker/README.md：Web 版环境变量表、QQ 音乐服务与 Navidrome 预置账号——Docker 自托管遇到问题时逐条查。
• docs/local-library-management.md：本地曲库导入、重扫、在线匹配与实体编辑——接本地音乐前先看一遍。
• sync-server/：官方同步服务端源码——多设备同步外观设置与 AI 主题库时部署它。

挑一条走通，剩下的交给歌词：丢一首带逐字歌词的歌进去，全屏动画跑起来，安装这件事就结束了。

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