企业官网建设流程全解析

Folia 全屏歌词动画播放器从下载到跑通第一首歌的完整安装指南

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

Folia 是一款把歌词做成全屏动画的音乐播放器，支持网易云、QQ 音乐、酷狗、Navidrome 这些在线平台，也能直接管你自己的本地曲库。这篇 Folia 安装与部署教程覆盖四种装法：桌面安装包、Arch AUR、通用 Linux 便携版、Docker 部署到 NAS。每一步都标了成功信号，你照做就能从下载走到听见第一首歌。

三个问题定路线

先别急着下载，问自己三个问题。

第一，你在哪台设备上听？如果是日常用的电脑，Windows、macOS 还是 Linux 都行，看桌面版一节；如果你用的是 Arch Linux，直接跳 AUR 一节，一条命令省掉手动解压。

第二，你的音乐从哪来？只在本地文件夹和 Navidrome 之间切，桌面版就够；在线平台账号也是装在桌面版里登录，不冲突。

第三，你要不要浏览器或者 NAS 也能访问？要，就只有一条路——Docker Web 版一节；不要，上面三种桌面路线任选。

桌面版：官方安装包最快启动 🖥️

准备：一台 Windows、macOS 或 Linux 电脑，不需要任何构建工具；网络能连上 Releases 页面，或者用网盘镜像。

执行：

1. 打开仓库 README 的「快速下载」一节，从 Releases 入口取最新版本：Windows 拿.exe安装包，macOS 拿.dmg。
2. Apple silicon（M 系芯片）选对应的 Apple silicon 版本，双击安装即可。
3. 装完从桌面图标启动 Folia。

【避坑】网盘镜像只收了 Windows 和 Apple silicon 两个正式安装包，Intel Mac 和 Linux 包不在里面，得回 Releases 页面自己取。

成功信号：双击图标能进 Folia 首页，搜索框、播放列表面板都正常渲染，说明安装没问题。

Arch Linux 用 AUR 一条命令装完

准备：Arch 或衍生发行版，已装好yay或paru（社区 AUR 包管理助手），网络能连到 Releases。

执行：

1. 终端里跑：

yay -S folia-major-bin

助手会自动装alsa-lib、gtk3、libxss、nss四个运行依赖，从 Releases 拉官方linux-x64.tar.gz，把整套文件部署到/opt/folia-major。

2. 打开应用菜单，搜folia-major，点一下启动。

【避坑】这个包本质是去 Releases 下载官方预编译包再本地打包，网络慢时构建会卡在下载环节，先确认网络再开跑，别干等。

成功信号：应用菜单里出现folia-major图标，启动后界面正常；/opt/folia-major下有完整的程序文件。

Linux 便携版手动部署 📦

准备：任意主流 Linux 桌面发行版，会终端基本操作；从 Releases 取到linux-x64.tar.gz压缩包。

执行：

1. 把压缩包解压到一个固定目录，比如~/Apps/Folia/。包里是三样东西：folia-major可执行文件、resources/linux/icon.png图标、resources/linux/folia-major.desktop启动项模板。
2. 把启动项模板复制进应用菜单目录：

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

3. 用文本编辑器打开复制出来的文件，把__APP_PATH__换成folia-major可执行文件的绝对路径，__ICON_PATH__换成resources/linux/icon.png的绝对路径。占位符的完整替换示例在 packaging/linux/README-LINUX.txt。
4. 如果你的桌面环境有要求，把这个.desktop文件标记为可信。

【避坑】可执行文件与resources/目录必须留在同一个便携包内，只复制一半启动不了。

成功信号：应用菜单出现folia-major，启动后能导入本地音频目录并列出歌曲。

Docker 部署 NAS 上的 Web 版 🐳

准备：一台装好 Docker Engine 24+ 和 Compose v2 的机器，NAS 也行；网络能拉取镜像。

执行：

1. 新建一个空目录，从仓库deploy/docker/目录取compose.yaml和环境变量模板.env放进去，整个目录只需要这两个文件。
2. 生成一串随机字符，填进.env的SYNC_TOKEN——同步服务必填，至少八位：

openssl rand -hex 32

命令会打印一串随机十六进制串，复制它粘到SYNC_TOKEN后面。

3. 校验配置并启动整个堆栈：

docker compose config docker compose up -d --wait

config先空跑一遍查语法，--wait会等所有容器健康检查通过才返回。

成功信号：浏览器打开http://<你的地址>:18080出现 Folia Web 首页，可以安装为 PWA（Progressive Web App，让网页像应用一样装进浏览器/桌面）；http://<你的地址>:13000/health返回 Sync Server 健康状态。

【避坑】网易云、酷狗、QQ 音乐和 Folia Web API 都不开放宿主机端口，统一走 gateway 转发，别给它们单独映射端口。Navidrome 预置账号等环境变量细节见 deploy/docker/README.md。

跑通第一首歌

不管走哪条路线，最后都看这三件事：

• 首页搜索平台名（网易云 / QQ / 酷狗）完成登录，或打开本地音乐库导入音频目录。
• 播放任意歌曲，歌词以全屏动画主题渲染，背景配色能按情绪由 AI 生成。
• 歌曲同目录的.lrc、.vtt歌词文件被自动识别，本地歌曲自动在线补全歌词与封面。

翻车急救

• 如果 Linux 启动后黑屏、透明度或模糊异常，就换软件渲染兜底方案重启：FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major（swiftshader 是用 CPU 模拟 GPU 的保底方案，牺牲性能换稳定）。
• 如果 swiftshader 仍不稳定，就退到最保守的纯软件渲染：FOLIA_LINUX_GRAPHICS_MODE=software ./folia-major。
• 如果 X11 下智能动感模式提示没有可用的 WebGPU，是 Vulkan 默认关闭了，用FOLIA_LINUX_VULKAN=1 ./folia-major --ozone-platform=x11手动开启，这个开关只在 X11 生效。
• 如果便携版无法启动，就检查可执行文件与resources/目录是不是被拆散了，放回同一个便携包目录再试。

这些环境变量只影响 Linux 桌面端的启动参数，不会改动 Web 版或同步服务的配置。

第一首歌响起来，安装就算落地了。壁纸模式、遥控窗和 Navidrome 接入的机制细节，继续翻 docs/technical.md。

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