企业官网建设流程全解析

Folia 安装指南：全屏歌词动画播放器，从桌面到 NAS 一次跑通

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器 A multi-platform music player for local files, Navidrome, and online streaming services, featuring stunning animated lyrics.项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major

Folia（folia-major）是一款把歌词渲染成全屏动画的音乐播放器：桌面端基于 Electron，Web 端基于 Node.js，支持网易云、QQ 音乐、酷狗、Navidrome 以及本地音乐库。按本文走完后，你可以在自己的电脑上装好桌面版、验收播放效果，或者把 Web 版部署到服务器和 NAS 上，用浏览器打开就能听歌看歌词动画。

先判断你要走哪条路线

Folia 不是只有"装个 App"一种玩法，选错路线会白忙一场。先对照自己的情况：

桌面端能接的音乐源更多（额外支持波点音乐、YouTube Music、Spotify、汽水音乐），Web 端覆盖网易云、QQ 音乐、酷狗与 Navidrome。如果你的需求是"本地歌曲 + 在线补全歌词封面"，桌面端优先；如果是"多台设备共享一个地址"，走 Web 版。

前置检查：动手前把这几件事确认掉

1. 下载渠道覆盖范围。官方网盘镜像（夸克 / 百度，百度提取码flia）只放了 Windows 和 Apple silicon Mac 两种安装包；Intel Mac、Linux 都不在网盘里，只能去项目 Releases 页面取对应平台的包。
2. 系统依赖。Docker 路线要求 Docker Engine 24 及以上和 Compose v2；AUR 路线要求先装好yay或paru，且系统具备alsa-lib、gtk3、libxss、nss依赖。
3. 浏览器环境（仅 Web 版）。本地音乐目录的导入依赖浏览器的 File System Access API，需要桌面版 Chromium 系浏览器；且该能力只在 HTTPS 安全上下文里可用，局域网 IP 的纯 HTTP 下会缺失。
4. 版本预期。仓库package.json当前版本为 0.7.25，AUR 包folia-major-bin目前停留在 0.1.4，落后较多，AUR 用户要有这个心理准备。

桌面端安装：按系统各走各的

Windows：网盘或 Releases 取安装器

• 从项目 Releases 页面下载 Windows 安装包；国内网络慢就改用网盘镜像（夸克或百度，提取码flia）。
• 下载前对一眼网盘里的版本号与最新 release，明显滞后就回 Releases 取。
• 双击安装器走完流程，在开始菜单找到 Folia 并启动。
• 做完应看到：Folia 出现在开始菜单，且能正常打开主窗口。

macOS：拖进 Applications，再解除隔离属性

• 到 Releases 页面下载与芯片对应的.dmg（arm64 或 x64），挂载后把Folia.app拖进Applications，不要在挂载盘里直接运行。
• 首次打开若提示"应用已损坏"或"无法验证"，在终端执行下面的命令移除下载隔离属性，让 Gatekeeper 不再拦截：

xattr -dr com.apple.quarantine /Applications/Folia.app # 移除下载隔离属性，对"已损坏"和"无法验证"两种提示都有效

• 然后从 Applications 重新启动应用。

当前发布的 macOS 版没有 Apple Developer ID 签名与公证，被 Gatekeeper 拦截属于正常现象，不是包坏了。同时它不支持应用内自动更新——每次下载新版覆盖安装后，Folia.app会重新带上隔离属性，上面的xattr命令要再执行一遍。完整排查思路见 docs/desktop/macos-app-damaged.md。

Linux：Arch 走 AUR，其他发行版走便携包

Arch / Manjaro（AUR 路线）

yay -S folia-major-bin # 从 AUR 安装，构建过程即下载 Releases 的 linux-x64 包并放入 /opt/folia-major

装完后用下面的命令确认软链接已挂到/usr/bin：

command -v folia-major # 预期输出 /usr/bin/folia-major

• 包会同时装好.desktop应用项和图标，从应用菜单启动即可。
• AUR 构建的实质是"下载二进制 + 建软链接"，如果卡在下载步骤（通常是网络问题），不用干等，直接改走下面的便携包路线。

Debian / Ubuntu / Fedora 等（便携包路线）

1. 到 Releases 页面按发行版取包：Debian 系取.deb，Fedora / RHEL 系取.rpm，其余发行版取形如folia-major-<version>-linux-x64.tar.gz的便携包。
2. 解压到一个固定目录，把整套程序放进一个你之后不会乱动的位置：

mkdir -p ~/Apps/Folia && tar -xzf folia-major-*-linux-x64.tar.gz -C ~/Apps/Folia # 解压便携包到固定目录

3. 便携包自带桌面项模板，复制到用户级应用目录：

cp ~/Apps/Folia/resources/linux/folia-major.desktop ~/.local/share/applications/ # 安装桌面启动项

4. 打开复制出的.desktop文件，把__APP_PATH__替换为folia-major可执行文件的绝对路径，__ICON_PATH__替换为resources/linux/icon.png的绝对路径；桌面环境有要求的话，再把该文件标记为可信。

便携包一共三样东西：folia-major可执行文件、resources/linux/icon.png、resources/linux/folia-major.desktop模板，详见 packaging/linux/README-LINUX.txt。排查启动问题时，先确认可执行文件与resources/目录在同一个便携包内。

首次启动与关键配置

1. 跳过两道引导弹窗。桌面版首启会依次出现"思索模式"和"资料库界面选择"的引导，确认或跳过即可，之后进入首页。
2. 登录在线音乐源。网易云、QQ 音乐、酷狗等需要各自登录一次；本地音乐库则是导入文件夹后自动建索引（索引存在本地，文件内容不上传）。
3. Web 版填好.env。自托管时唯一必填项是SYNC_TOKEN（至少 8 位），用下面命令生成随机串填进去：

openssl rand -hex 32 # 生成 SYNC_TOKEN 用的随机字符串

AI 主题相关配置可以留空，不影响播放音乐。跨设备同步主题后，在 Folia「设置 → 连接与集成」填入服务端地址和SYNC_TOKEN即启用同步。

Web 版如何跑起来（Docker Compose）

1. 新建一个空目录，把仓库里的deploy/docker/compose.yaml和deploy/docker/.env.example放进去，后者改名为.env；字段含义逐行有注释，完整说明见 deploy/docker/README.md。
2. 按上一节生成并填入SYNC_TOKEN，确认FOLIA_IMAGE_NAMESPACE不为空（缺失时 Compose 会直接拒绝启动）。
3. 校验配置并启动，--wait会等全部健康检查通过才返回：

docker compose config && docker compose up -d --wait # 校验配置、拉取镜像并启动全栈

4. 浏览器打开http://<服务器IP>:18080进 Web 首页；Sync Server 的健康检查地址是http://<服务器IP>:13000/health。
5. 做完应看到：docker compose ps里各服务均为 healthy，网页能打开并登录音乐源。

只对外发布 Web 网关 18080 与 Sync Server 13000 两个端口，其余服务仅走 Docker 内部网络。要正式使用本地音乐目录，需要让 NAS 的反向代理终止 HTTPS：证书必须是浏览器信任的完整链（自签根证书不算），反向代理要透传Host、X-Forwarded-Host、X-Forwarded-Proto、X-Forwarded-For，并把FOLIA_TRUSTED_PROXIES填成代理本身的确切地址；应用不支持挂载到/folia/子路径。纯 HTTP 下在线搜索、播放和歌词都正常，但目录导入、输出设备选择、PWA 安装等能力会缺失或降级。

启动后如何验收

以下任一组条件满足，就算装好了：

• 桌面版：Folia 出现在应用菜单（Windows 看开始菜单、macOS 看 Applications、Linux 看应用菜单），能打开主窗口。
• 首页能看到 Playlists / Radio / Albums / Folder 等标签页和搜索框。
• 进入任意一首歌能正常播放，全屏歌词动画出现。

出问题时的排查方向

Linux 黑屏时的两条兜底命令：

FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major # 用 swiftshader 软件渲染启动 FOLIA_LINUX_GRAPHICS_MODE=software ./folia-major # 仍不稳定时，改用更保守的软件渲染档位

X11 环境下若提示智能动感模式无可用 WebGPU，可尝试FOLIA_LINUX_VULKAN=1 ./folia-major --ozone-platform=x11；该变量只对 X11 生效，原生 Wayland 下会被忽略（开启反而可能让 GPU 进程崩溃）。

延伸资料

• packaging/linux/README-LINUX.txt：FOLIA_LINUX_GRAPHICS_MODE、FOLIA_LINUX_VULKAN图形变量全解，以及壁纸模式（需 Wayland 合成器支持wlr-layer-shell，GNOME 不支持）的细节。
• docs/technical.md：更新通道、安装包获取方式、开发环境与常用脚本。
• deploy/docker/README.md：Docker 全栈的端口、环境变量表、QQ 音乐登录态持久化、Navidrome 预置账号与 HTTPS 要求。
• docs/local-library-management.md：本地音乐导入、重扫、在线匹配与实体编辑的完整说明。

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器 A multi-platform music player for local files, Navidrome, and online streaming services, featuring stunning animated lyrics.项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major