Folia 安装实操：十分钟从下载跑到全屏歌词动画

Folia 安装实操：十分钟从下载跑到全屏歌词动画

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

这篇文章只帮你解决一件事：把 Folia 安装在本机跑起来，播放第一首带全屏歌词动画的歌。桌面 Windows、macOS、Linux，还是 NAS 上 Docker 自托管，四条路线任选一条，读完就能动手。

30 秒确定你的 Folia 安装路线

• 系统→ Windows / macOS / Linux 各有对应安装包，Arch 系另走 AUR
• Mac 芯片→ Apple silicon 用 arm64 包，Intel 用 x64 包；官方网盘只有 arm64
• 网络→ 能直连 GitHub Releases 就走直连；不顺时 Windows 与 arm64 Mac 可改走官方网盘
• 场景→ 只在电脑上用选桌面版；要手机、浏览器都能访问选 Docker Web 版

⚠️ 仓库当前版本 0.7.23，实际以 Releases 最新条目为准。网盘与 AUR 包都会滞后，下载前先比对文件名里的版本号。

一张表看清四条路线的耗时与特点

下面按路线展开，直接跳到你那节即可。

Windows：下载官方 exe 跑完 NSIS 安装向导

1. 从官方 Releases 页面下载最新版Folia-Setup-<版本>.exe；网络不顺的走官方网盘（百度提取码flia），建议先转存到自己网盘，中断可续传。预期：文件下完，大小与页面一致。
2. 双击运行 exe，进入 NSIS 向导，安装目录可以改，保持默认一路确认。预期：安装结束，桌面与开始菜单出现 Folia 快捷方式。
3. 从开始菜单启动。预期：主界面正常加载，只装官方渠道的分发包。

macOS：按芯片选对 dmg 拖进 Applications

1. 打开「关于本机」看芯片：Apple silicon 下Folia-<版本>-arm64.dmg，Intel 下Folia-<版本>-x64.dmg。官方网盘只有 arm64，Intel Mac 必须走 Releases。预期：dmg 下载完整。
2. 打开 dmg，把Folia.app拖进Applications，别直接在挂载盘里运行。预期：应用程序文件夹里出现Folia.app。
3. 首次打开若提示「应用已损坏」，是缺 Apple Developer ID 签名被拦截，不是真损坏，在终端执行后重新打开：

xattr -dr com.apple.quarantine /Applications/Folia.app

预期：不再弹窗，正常进入播放界面。

💡 macOS 版暂不支持应用内自动更新，每次覆盖安装新 dmg 后都要重跑一次上面的命令。

拦截原理与「隐私与安全性」备选方案见 macOS 已损坏提示说明。

Linux：一行命令跑起 Folia Linux 便携包

1. Arch 系先确认装了 AUR helper，再执行：

yay -S folia-major-bin

alsa-lib、gtk3、libxss、nss依赖自动解决，程序装进/opt/folia-major。预期：应用菜单里能搜到 Folia。 2. 其他发行版从 Releases 下载folia-major-<版本>-linux-x64.tar.gz，解压后在该目录直接启动：

./folia-major

预期：窗口正常打开。 3. 需要桌面启动项时，把resources/linux/folia-major.desktop复制到~/.local/share/applications/，将__APP_PATH__、__ICON_PATH__替换为可执行文件与resources/linux/icon.png的绝对路径，再按桌面环境要求标记为可信。预期：菜单启动与命令行是同一个窗口。

⚠️ AUR 包基于预编译 Release 打包、版本滞后；要最新版就先手动下好同版本 tar.gz 放进源码目录，再makepkg -si。

黑屏、透明度异常、Vulkan 与 Wayland 细节见 Linux 便携版说明。

NAS：用 Docker Compose 部署 Folia NAS 自托管

1. 建一个空部署目录：

mkdir folia-docker && cd folia-docker

2. 从仓库deploy/docker/目录取compose.yaml与.env.example放进当前目录，后者改名为.env。预期：目录里只有这两个文件。
3. 生成同步 Token，粘贴进.env的SYNC_TOKEN：

openssl rand -hex 32

FOLIA_IMAGE_NAMESPACE保持模板默认的papersman，AI 密钥留空不影响播放。 4. 确认 Docker Engine 24+ 与 Compose v2，然后校验并启动：

docker compose config && docker compose pull && docker compose up -d --wait

预期：docker compose ps全部服务 healthy。 5. 浏览器打开http://NAS-IP:18080进入 Web 端，http://NAS-IP:13000/health检查 Sync Server。预期：首页能搜索并播放。

⚠️ 本地音乐目录访问依赖可信 HTTPS 安全上下文，NAS 正式使用需自配反向代理与证书，且不支持挂载到/folia/子路径。

完整环境变量、Navidrome 预置与回滚方法见 Docker 部署说明。

验证 Folia 安装结果只需三个动作

1. 打开「关于」页：版本号与下载文件名一致。
2. 登录一个在线音源（网易云 / QQ / 酷狗），或导入一个本地音乐文件夹：搜索能出结果。
3. 播放一首带歌词的歌：全屏歌词动画渲染正常，即安装通过。

踩坑速查：五种启动报错一行修复

• 下载一直中断→ 直连 GitHub 超时 → Windows 与 arm64 Mac 换官方网盘续传；Intel Mac 与 Linux 包重走 Releases。
• macOS 提示「应用已损坏」→ 缺 Apple Developer ID 签名被 Gatekeeper 拦截 → 终端执行xattr -dr com.apple.quarantine /Applications/Folia.app后重新打开；macOS 15 起 Control 点击打开已失效，别浪费时间。
• Linux 黑屏、透明度异常或 GPU 闪退→ 图形栈兼容问题 → 先FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major，仍不稳再换software；X11 缺 WebGPU 时可FOLIA_LINUX_VULKAN=1 ./folia-major --ozone-platform=x11，原生 Wayland 下不要开 Vulkan。
• dmg 解压后打不开→ 下载中断导致文件不完整 → 重新下载，并确认运行的是Applications里的正式版，不是挂载盘里的临时版本。
• Docker 起不来或 sync-server 反复重启→SYNC_TOKEN没填或不足八位 → 用openssl rand -hex 32生成后回填，再docker compose up -d --wait。

一条 Folia 安装到这里就闭环了。桌面版下一步是挑歌词动画主题与调参，Web 版下一步是接 Navidrome 与在线音源，具体看下一篇功能上手指南。

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