Folia 歌词动画播放器安装与首跑指南：十分钟从下载到全屏歌词动效

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

Folia 是一个基于 Electron 的全屏沉浸式歌词动画音乐播放器，支持本地音乐库、Navidrome，以及网易云、QQ 音乐、酷狗等在线音源。本文带你走完「选包 → 安装 → 启动 → 验证」的完整链路：读完后你就能在自己的系统上启动主窗口，点开歌曲看到全屏歌词动画。桌面版内置前后端运行环境，全程无需另装依赖。

装完 Folia 后你拥有什么

• 一个带搜索栏与专辑卡片墙的主窗口，播放歌曲时呈现全屏歌词动画，内置多种主题风格
• 可导入本地文件夹的音乐库，自动读取元数据、同目录歌词与封面
• 一套可复用的启动命令与报错速查，后续排查问题直接用

安装前检查：系统与拿包路由

先对照下表确定你要拿哪个包：

⚠️ 只认官方入口下发的包。官方网盘链接见 README.md「快速下载」小节（百度盘提取码flia），网盘只收录 Windows 与 Apple silicon 正式版，没有 Linux 包。

网络与权限准备：

• 能访问仓库 Releases 页或官方网盘；建议先转存到自己的网盘再下载，断流可续传
• Windows、macOS 桌面版内置前后端运行环境，无需 Node.js 等依赖
• Arch 路线需要任意一个 AUR Helper（yay或paru）
• Web 部署路线需要 Docker，并可用openssl生成随机 Token

Windows 主线：从下载包到主窗口打开

1. 到仓库 Releases 页下载最新版Folia-Setup-<版本>.exe（国内网络走官方网盘镜像）。预期：下载完成，文件能正常打开。
2. 双击 exe，按默认安装路径一路点完。预期：安装结束，开始菜单里出现「Folia」图标。
3. 从开始菜单打开 Folia。预期：主窗口弹出，顶部是搜索栏，中间是专辑卡片墙。
4. 点任意一首歌播放。预期：歌曲开始播放，全屏歌词动画出现，进度条随时间走动。

✅ 中间检查点：看到歌词动画即主线通过。若窗口打开但全黑，直接查文末「启动报错速查」。

其他平台安装速览

macOS（Apple 芯片）安装 dmg

1. 同样从「快速下载」网盘链接拿包，选Folia-<版本>-arm64.dmg，转存后下载。
2. 双击 dmg，把 Folia 图标拖进应用程序文件夹。预期：Launchpad 里出现 Folia 图标。
3. 从 Launchpad 点开 Folia。预期：主窗口带歌词动画打开。
4. 首次启动若提示「应用已损坏」，右键 Folia 图标选择「打开」。隔离属性处理细节见 docs/desktop/macos-app-damaged.md。

Linux 便携版解压启动

1. 到 Releases 页下载folia-major-<版本>-linux-x64.tar.gz，版本号与网盘镜像保持一致。
2. 放到不会被清理的固定目录后解压：

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

3. 用可执行文件直接启动：

./folia-major

预期：终端不报致命错误，主窗口弹出。

4. 想要桌面启动项，把模板复制到用户级应用目录：

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

再把文件里__APP_PATH__与__ICON_PATH__两个占位符替换为真实绝对路径，完整示例见 packaging/linux/README-LINUX.txt；桌面环境有要求时记得把该.desktop文件标记为可信。

Arch Linux 用 AUR 构建安装

1. 没有 AUR Helper 先装一个，yay或paru都行。
2. 执行构建安装：

yay -S folia-major-bin

alsa-lib、gtk3、libxss、nss会自动装好。

3. 若卡在拉取 tar.gz，先把同版本文件放进构建目录的源码目录，再继续：

makepkg -si

4. 用包管理器核对：

pacman -Qs folia-major

预期：输出里出现folia-major-bin条目。构建逻辑见 packaging/aur/folia-major-bin/PKGBUILD。

Web 自托管 Docker 全栈部署

1. 本地没有仓库源码就先克隆：

git clone https://gitcode.com/GitHub_Trending/fo/folia-major

2. 新建一个空目录folia-docker，把仓库里deploy/docker/compose.yaml与deploy/docker/.env.example两个文件复制进去，.env.example改名为.env。
3. 生成同步 Token 并填入.env的SYNC_TOKEN（至少八位）：

openssl rand -hex 32

AI 配置留空即可，不影响播放。 4. 验证配置并启动：

docker compose config docker compose up -d --wait

预期：docker compose ps里各容器状态为 running。 5. 浏览器打开http://<服务器IP>:18080。预期：Folia Web 主页加载；再访问http://<服务器IP>:13000/health应返回健康状态。 6. 环境变量、QQ 音乐与 Navidrome 预置账号的完整配置见 deploy/docker/README.md。

安装后如何验证：三个启动验收信号

✅ 满足任意一条即通过：

• Folia 主窗口能打开，看得到搜索栏与专辑卡片，播放歌曲时有全屏歌词动画。
• Linux 便携版目录下运行./folia-major，弹出带歌词的主窗口。
• Arch 上pacman -Qs folia-major输出里有folia-major-bin条目；或 Web 部署的http://<服务器IP>:18080能在浏览器中正常打开。

启动报错速查：按症状对号

下一步去哪：接曲库与进阶部署

• 接本地音乐：主界面「Import Folder」导入本地音乐文件夹，自动读取元数据、同目录歌词与封面，完整说明见 docs/local-library-management.md。
• 接 Navidrome 与在线音源：在「设置 → 连接与集成」填服务器地址，网易云、QQ 音乐、酷狗可直接接，能力一览见 README.md「核心能力」。
• 开壁纸模式：在「选项 → 桌面端」开启「壁纸模式」，主窗口沉到所有窗口之下当桌面歌词壁纸，见 docs/wallpaper-mode.md。
• 装模组：在「设置 → 模组 → 模组系统」开启后，把模组 zip 拖进面板即可安装，平台规范与示范模组见 mods/README.md。
• 跨设备同步主题：自托管部署sync-server（Cloudflare Workers、Docker 或 Node.js 三种方式），说明见 sync-server/README.md。

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