folia-major 安装与首次跑通指南：30 分钟点亮全屏歌词动画
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia（仓库名 folia-major）是一款以全屏沉浸式歌词动画为核心的音乐播放器：本地音乐文件夹、Navidrome、网易云 / 酷狗 / QQ 音乐在线平台都能放，把歌词渲染成全屏动画。支持 Windows / macOS / Linux 桌面端与 Web 版，当前正式版0.7.23。跟着下文拿包、装上、接上音源，就能跑通。
动手前清单：系统、安装包、音源
- 系统：Windows、macOS（Apple silicon）或 Linux x86-64 桌面
- 安装包：到项目官方 Releases 页选对应平台包，当前版本号
0.7.23，文件名里的数字要对得上 - 音源：三选一，至少备齐一种
- 本地音乐文件夹（支持 MP3、FLAC、M4A、WAV、OGG、Opus、AAC）
- 网易云 / 酷狗 / QQ 音乐账号（桌面版另支持波点音乐、YouTube Music、Spotify 等）
- 自托管的 Navidrome 服务
💡 没有在线账号就先备本地音乐，首次跑通走这条最稳。
Folia 0.7.23 安装步骤：Windows、macOS、Linux 三条路
Windows
- Releases 里选
Folia-Setup-0.7.23.exe - 双击安装包，跟着向导点到底
成功标志：开始菜单里出现 Folia，启动后主窗口正常出来。
macOS
- Apple silicon 选
Folia-0.7.23-arm64.dmg（Intel 选 x64 包） - 打开 dmg，把
Folia.app拖进Applications，别在挂载盘里直接运行
成功标志：启动台里能看到 Folia。
⚠️ 当前版本未做 Apple 公证，首次打开可能被拦成"已损坏 / 无法验证"，见下文故障排查。
Linux
- 选
folia-major-0.7.23-linux-x64.tar.gz（也有 deb / rpm） - 解压：
tar -xzf folia-major-0.7.23-linux-x64.tar.gz - 包内是
folia-major可执行文件、resources/linux/icon.png和桌面启动模板resources/linux/folia-major.desktop。要建桌面启动项，把模板复制到~/.local/share/applications/，再把其中的__APP_PATH__、__ICON_PATH__换成实际绝对路径 - 直接跑：
./folia-major
成功标志：窗口出不黑屏，能看到首页的歌单区与搜索框。
首次跑通：接上音源，让全屏歌词亮出来
本地音乐路线：进入首页的本地音乐区域，点"导入文件夹"选中音乐目录。Folia 递归扫描，读取元数据与同目录同名歌词文件（.lrc、.vtt等），扫完歌曲卡片上墙。
在线平台路线：在账号入口登录网易云、酷狗或 QQ 音乐，搜索一首歌，点播放。
Navidrome 路线：在 Navidrome 入口填服务器地址，NAS 上的曲库直接可播。
三条路线的成功标志都一样：主窗口不黑屏、能看到首页；点播放后歌词亮出全屏动画且正常出声。全屏歌词动画有多种排版风格可切换，下面这种就是其中之一。
💡 歌词没对上时，先查同目录.lrc文件是否与音频同名（track.lrc或track.mp3.lrc都认）。
故障排查：黑屏、被拦、版本对不上
现象：Linux 启动黑屏、透明度/模糊异常或 GPU 崩溃
原因：GPU 图形路径冲突，Linux 上最常见。
解法：
FOLIA_LINUX_GRAPHICS_MODE=swiftshader ./folia-major
仍不稳定就把取值换成software。这些变量只影响 Electron 的 Linux 启动参数，Wayland 与壁纸模式细节见 packaging/linux/README-LINUX.txt。
现象：macOS 弹"Folia.app 已损坏"或"Apple 无法验证"
原因：当前版本未接入 Apple Developer ID 签名与 notarization，Gatekeeper 拦截了下载隔离属性，包本身没坏。
解法：终端执行
xattr -dr com.apple.quarantine /Applications/Folia.app
再从Applications重新打开。
⚠️ macOS 版不支持应用内自动更新，每次覆盖安装新版本后隔离属性会重新带上，这条命令要再跑一次。仍打不开的进一步处理见 docs/desktop/macos-app-damaged.md。
现象：网盘镜像里的版本号和 Releases 对不上
原因：镜像可能滞后一个版本。
解法：以 Releases 页版本号为准，直接取最新包，核对文件名里的0.7.23。
其它安装入口：AUR、Docker 自托管、PWA
- Arch 系：
yay -S folia-major-bin一条命令装进/opt/folia-major并生成启动项。代价是构建时要拉一次 Release 包，下载慢会卡住——手动把folia-major-0.7.23-linux-x64.tar.gz放进构建目录，再跑makepkg -si。 - Web / 自托管：想在手机、平板上听，或部署到 NAS，看仓库
deploy/docker/目录下的 Docker 全栈部署文档（要求 Docker Engine 24+，Web 默认端口 18080），起服务后在浏览器把网页装成 PWA。代价：服务要自己托管。
包装好、音源接上，全屏歌词动画已经在你屏幕上了。
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
