企业官网建设流程全解析

如何 3 分钟装好 Folia：歌词动画播放器国内安装完整指南

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

从 GitHub Releases 直连下载 Folia 安装包，常见现象是速度掉到几十 KB/s，一两百 MB 的包下到一半断流，还得从头再来。这份指南给出 4 条国内可用的路径：Windows / macOS 走官方网盘镜像，Arch 用 AUR 包一条命令，其他 Linux 用便携版压缩包解压即用，NAS 用户用 Docker Compose 起 Web 版。Folia 是一款以全屏歌词动画为核心的播放器，支持网易云、酷狗、QQ 音乐、Navidrome 和本地音乐库，桌面版内置前后端运行环境，装完不用自己配后端。

先看这张表：你的系统走哪条路

Windows / macOS 怎么下载：官方网盘镜像 3 步装完

适合：Windows 全版本与 Apple silicon 的 Mac，不想折腾代理的普通用户。

1. 打开本仓库 README.md 的「快速下载」一节，找到官方夸克网盘 / 百度网盘两个入口——看到两条网盘地址即完成。
2. 在网盘客户端里转存后下载对应平台的包：Windows 选.exe，macOS 选.dmg且认准 Apple silicon 版本，下载完成的文件大小应与页面标注一致。
3. 双击安装包按提示点完，不用额外装 Node、配数据库——打开应用看到主窗口即安装成功。

避坑：网盘镜像只覆盖 Windows 与 Apple silicon 的正式版，Linux 包不在网盘里，别翻半天；镜像更新可能滞后一个版本，下载前先对照官方 Releases 的版本号，别拿错旧包。

Arch 怎么装：AUR 包 folia-major-bin 一条命令

适合：Arch Linux 用户，希望装好后跟着包管理器一起更新。

1. 确认 AUR Helper 已就位，执行yay --version——看到版本号输出即成功；没装的话先按 Arch 官方 wiki 把yay（或paru）装上。
2. 执行安装：

yay -S folia-major-bin

构建会自动拉取 Linux 便携版，把文件装进/opt/folia-major，软链命令并注册桌面项——构建日志走完、应用菜单里出现 Folia 启动项即完成。依赖alsa-lib、gtk3、libxss、nss会随构建自动安装。

3. 在终端确认命令就位：

which folia-major

输出/usr/bin/folia-major即安装完成。

避坑：构建卡在拉取folia-major-<版本号>-linux-x64.tar.gz这一步时，别反复重试构建——先手动把同版本压缩包放进 yay 的构建源码目录，再执行makepkg -si，就能跳过慢速下载。

其他 Linux 发行版怎么装：便携版压缩包解压即用

适合：Ubuntu、Fedora、Debian 等没有 AUR 的发行版。注意 Linux 包不在网盘镜像范围内，需要从官方 Releases 页面直接下载folia-major-<版本号>-linux-x64.tar.gz，国内网络慢时可以临时挂代理。

1. 下载对应版本的folia-major-<版本号>-linux-x64.tar.gz后解压：

tar -xzf folia-major-<版本号>-linux-x64.tar.gz

解压出的目录里应有folia-major可执行文件和resources/子目录，两者同级即正确。

2. 在解压目录里启动：

./folia-major

看到主窗口正常渲染即成功，程序不需要初始化数据库或后端。

3. 想要桌面启动项的话，把resources/linux/folia-major.desktop复制到~/.local/share/applications/，将文件里的__APP_PATH__和__ICON_PATH__占位符替换成可执行文件与resources/linux/icon.png的绝对路径——重启桌面或重新打开应用菜单，看到 Folia 图标即完成。详细说明见 packaging/linux/README-LINUX.txt。

避坑：folia-major可执行文件必须和resources/保持在同一目录，把可执行文件单独拷去别处会导致图标和启动项模板丢失。

NAS 上跑 Web 版：Docker Compose 快速部署

适合：想全家设备（含手机）通过浏览器访问 Folia 的 NAS 用户。要求 Docker Engine 24+ 与 Docker Compose v2，完整说明见 deploy/docker/README.md。

1. 新建一个空目录，从仓库deploy/docker/目录里取compose.yaml和.env.example两个文件放进目录，把后者重命名为.env——目录里最终只有这两个文件即正确。
2. 生成同步令牌并填进.env：

openssl rand -hex 32

把输出粘贴到SYNC_TOKEN，并确认FOLIA_IMAGE_NAMESPACE=papersman存在——配置项齐了才能往下走。

3. 校验并启动：

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

docker compose ps里各服务状态为 Up 即部署成功，随后浏览器打开http://NAS-IP:18080应看到 Folia Web 首页，Sync Server 健康检查地址是http://NAS-IP:13000/health。

避坑：.env里缺FOLIA_IMAGE_NAMESPACE或SYNC_TOKEN太短时 Compose 会直接拒绝启动，报错信息会指出具体缺哪一项，补齐即可。

装完怎么验证：3 个肉眼检查点 + 1 条命令

装完别急着关窗口，按顺序过 3 个检查点，每个都只需几秒钟：

1. 主窗口打开不黑屏、界面元素完整渲染；
2. 能连上音乐源——网易云、本地音乐库、Navidrome 任选其一，首页能刷出歌单或歌曲卡片；
3. 点任意歌曲播放，看到全屏歌词动画逐行动效出现，说明播放器与歌词渲染链路都通了。

本地音乐库连上后的效果参考下图，Folder 页签能刷出「All Songs」卡片即说明索引正常：

走 AUR 安装的话再加一条命令行验证，which folia-major输出/usr/bin/folia-major即命令就位；Docker 部署则以docker compose ps全 Up 加浏览器能打开 18080 端口为准。

下载失败或版本对不上怎么办：3 个高频卡点

Q1：Linux 启动后黑屏、透明度异常或 GPU 崩溃？显卡驱动与 Electron 的 GPU 加速不兼容所致。切软件渲染启动：

FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major

仍不稳定就换最保守的FOLIA_LINUX_GRAPHICS_MODE=software，恢复系统路径用FOLIA_LINUX_GRAPHICS_MODE=system。

Q2：网盘里的包和最新正式版对不上？网盘镜像更新滞后，且只收 Windows 与 Apple silicon 的正式版。以官方 Releases 页面的版本号为准，对不上就去 Releases 拿最新包。

Q3：AUR 构建长时间停在下载压缩包那一步？构建机直连 Releases 带宽受限。手动下载同版本folia-major-<版本号>-linux-x64.tar.gz放进构建源码目录，再执行makepkg -si跳过下载。

装得快不快，3 分钟见分晓；装完后全屏歌词动画跑起来的那一刻，这套流程就值回票价了 🎵

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