Folia 安装与首次使用教程：10 分钟跑通全屏歌词动画播放器
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia 是一款以全屏沉浸式歌词动画为核心的开源音乐播放器，能管理本地音乐库，也能接入网易云、酷狗、Navidrome 等在线平台。本教程带零基础的你走完下载、启动与初始配置，做完后能看到全屏歌词在自己的屏幕上动起来。全程预计 10~20 分钟。
先看完成后的样子
装好并导入歌曲后，Folia 会把整块窗口变成歌词舞台：播放时逐字歌词按不同动画主题在屏幕上流动，背景和配色可以由 AI 根据歌曲内容自动生成。本地曲库则以海报墙的形式展示封面、专辑与歌手，在线账号登录后搜索即播，歌词与封面自动加载。
先选你的路线
桌面版内置前后端运行环境，Windows / macOS / Linux 均可直接装；磁盘预留 1 GB 以上，能打开仓库 Releases 页即满足网络要求。各路线对比：
| 路线 | 适用环境 | 耗时 | 一句话关键差异 |
|---|---|---|---|
| 官方安装包（推荐） | Windows、macOS、Linux | 约 10 分钟 | 桌面版即装即用，从 README「快速下载」进 Releases 页拿包 |
| 网盘直链 | Windows、macOS（Apple silicon） | 约 10 分钟 | 国内网络更快，仅提供这两个平台的正式版安装包 |
| AUR 一条命令 | Arch Linux | 约 20 分钟 | 自动拉取 Linux 包并装到/opt/folia-major |
| Flatpak | 其他 Linux 发行版 | 视网络而定 | 社区第三方维护，包名 folia-major |
| Docker Compose | 服务器 / NAS | 视环境而定 | Web 全栈部署，浏览器访问，见 deploy/docker/README.md |
非推荐路线一行搞定：Arch 执行yay -S folia-major-bin（习惯 paru 的自行替换），验证pacman -Qs folia-major能看到folia-major-bin条目；Flatpak 直接装包名folia-major即可；Docker 路线按 Docker 部署说明 下载compose.yaml与.env模板后执行docker compose up -d --wait，再访问http://NAS-IP:18080验证。AUR 构建脚本见 packaging/aur/folia-major-bin/PKGBUILD。
推荐路线逐步走
打开仓库 README.md，找到「快速下载」小节，从 GitHub Releases 入口进入版本页（国内网络慢就点同小节的网盘入口，百度云提取码
flia）。验证：页面列出了 Windows / macOS / Linux 各平台安装包。按系统下载对应文件：Windows 选
.exe，macOS 选.dmg（Apple silicon），Linux 选folia-major-<版本>-linux-x64.tar.gz，版本号以 Releases 页最新条目为准。验证：下载进度完成、文件未中断。安装或解压。Windows 与 macOS 双击安装包按提示装完即可；Linux 把压缩包解压到任意固定目录，例如
~/Apps/Folia。验证：该目录里能看到folia-major可执行文件和resources/资源目录。启动应用。Windows 从开始菜单、macOS 从 Launchpad 找到 Folia 图标打开；Linux 在终端执行：
cd ~/Apps/Folia ./folia-major验证：弹出应用窗口并出现全屏歌词界面，走到这里就成功了一大半。
- （Linux 可选）建桌面启动项：把包内
resources/linux/folia-major.desktop复制到~/.local/share/applications/，再按 Linux 安装说明 把文件中的__APP_PATH__与__ICON_PATH__替换为实际绝对路径。验证：应用菜单出现 Folia 项，双击能开窗。
装完先做这几件事
- 导入本地音乐库。进入首页的本地音乐区域，选择「导入文件夹」并选中你的音乐目录，支持 MP3、FLAC、M4A、WAV、OGG 等格式，同目录同名的
.lrc等歌词文件会被自动识别，完整规则见 本地音乐库管理。验证：海报墙里能看到导入的歌曲列表。
- 登录在线音乐账号。在登录页选择网易云、酷狗或 Navidrome 并登录，本地歌曲还会自动回退匹配在线歌词与封面。验证：搜索一首歌能播放，右侧面板显示歌词、旁边显示封面。
- 试听一首带逐字歌词的歌，体验全屏歌词动画。AI 会根据歌曲情绪与歌词内容生成沉浸式背景，效果类似下图的内置主题。桌面党还可以到「选项 → 桌面端」开启壁纸模式，把整个窗口沉到所有窗口之下当桌面歌词（需 Wayland 合成器支持
wlr-layer-shell，GNOME 不支持，切换开关后应用会自动重启）。验证：切到浏览器等其他应用时，桌面仍显示歌词。
卡住了？快速排错
| 症状 | 可能原因 | 解决办法 |
|---|---|---|
| Linux 启动黑屏、透明度或模糊异常 | 显卡渲染兼容问题 | 改用软件渲染：FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major，仍不稳定再换software |
| 提示「需要恢复本地音乐访问权限」 | 重启后系统收回了目录读取权限 | 按界面提示重新授权；目录被移动过就对该文件夹执行「重新导入」 |
| AUR 构建卡在下载压缩包 | Releases 拉取速度慢 | 提前下载同版本 tar.gz 放进构建源码目录，再执行makepkg -si |
| 网盘版本和最新版对不上 | 网盘镜像更新有延迟 | 以 README「快速下载」入口为准，回 Releases 页核对版本号 |
| Web 版无法文件夹导入 | 浏览器不支持 File System Access API | 换支持的浏览器，或改用桌面版 |
日常使用直接从应用菜单打开 Folia 即可，本地曲库在海报墙的集合操作里执行「重新导入」就能增量更新。之后有新版本时，按同一条路线重装覆盖即可，版本号一律以仓库 README 与 Releases 页为准 🎵
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考