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-majorFoliafolia-major是一款把歌词渲染成全屏动画的音乐播放器桌面端基于 ElectronWeb 端基于 Node.js支持网易云、QQ 音乐、酷狗、Navidrome 以及本地音乐库。按本文走完后你可以在自己的电脑上装好桌面版、验收播放效果或者把 Web 版部署到服务器和 NAS 上用浏览器打开就能听歌看歌词动画。先判断你要走哪条路线Folia 不是只有装个 App一种玩法选错路线会白忙一场。先对照自己的情况你的实际情况推荐路线最终拿到的东西只想在自己电脑上听不想折腾桌面版Windows / macOS / Linux 安装包一个从应用菜单启动的播放器程序没有 PC或想让手机、电视、电脑都能用Docker 自托管 Web 版服务器/NAS 上的一个网址浏览器打开即用只想要同步服务不要整套 Web单独部署sync-server跨设备同步主题与设置的服务地址Arch / Manjaro 桌面习惯 AURAUR 的folia-major-bin包与桌面版等价但由 AUR 代劳下载和软链接桌面端能接的音乐源更多额外支持波点音乐、YouTube Music、Spotify、汽水音乐Web 端覆盖网易云、QQ 音乐、酷狗与 Navidrome。如果你的需求是本地歌曲 在线补全歌词封面桌面端优先如果是多台设备共享一个地址走 Web 版。前置检查动手前把这几件事确认掉下载渠道覆盖范围。官方网盘镜像夸克 / 百度百度提取码flia只放了 Windows 和 Apple silicon Mac 两种安装包Intel Mac、Linux 都不在网盘里只能去项目 Releases 页面取对应平台的包。系统依赖。Docker 路线要求 Docker Engine 24 及以上和 Compose v2AUR 路线要求先装好yay或paru且系统具备alsa-lib、gtk3、libxss、nss依赖。浏览器环境仅 Web 版。本地音乐目录的导入依赖浏览器的 File System Access API需要桌面版 Chromium 系浏览器且该能力只在 HTTPS 安全上下文里可用局域网 IP 的纯 HTTP 下会缺失。版本预期。仓库package.json当前版本为 0.7.25AUR 包folia-major-bin目前停留在 0.1.4落后较多AUR 用户要有这个心理准备。桌面端安装按系统各走各的Windows网盘或 Releases 取安装器从项目 Releases 页面下载 Windows 安装包国内网络慢就改用网盘镜像夸克或百度提取码flia。下载前对一眼网盘里的版本号与最新 release明显滞后就回 Releases 取。双击安装器走完流程在开始菜单找到 Folia 并启动。做完应看到Folia 出现在开始菜单且能正常打开主窗口。macOS拖进 Applications再解除隔离属性到 Releases 页面下载与芯片对应的.dmgarm64 或 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。LinuxArch 走 AUR其他发行版走便携包Arch / ManjaroAUR 路线yay -S folia-major-bin # 从 AUR 安装构建过程即下载 Releases 的 linux-x64 包并放入 /opt/folia-major装完后用下面的命令确认软链接已挂到/usr/bincommand -v folia-major # 预期输出 /usr/bin/folia-major包会同时装好.desktop应用项和图标从应用菜单启动即可。AUR 构建的实质是下载二进制 建软链接如果卡在下载步骤通常是网络问题不用干等直接改走下面的便携包路线。Debian / Ubuntu / Fedora 等便携包路线到 Releases 页面按发行版取包Debian 系取.debFedora / RHEL 系取.rpm其余发行版取形如folia-major-version-linux-x64.tar.gz的便携包。解压到一个固定目录把整套程序放进一个你之后不会乱动的位置mkdir -p ~/Apps/Folia tar -xzf folia-major-*-linux-x64.tar.gz -C ~/Apps/Folia # 解压便携包到固定目录便携包自带桌面项模板复制到用户级应用目录cp ~/Apps/Folia/resources/linux/folia-major.desktop ~/.local/share/applications/ # 安装桌面启动项打开复制出的.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/目录在同一个便携包内。首次启动与关键配置跳过两道引导弹窗。桌面版首启会依次出现思索模式和资料库界面选择的引导确认或跳过即可之后进入首页。登录在线音乐源。网易云、QQ 音乐、酷狗等需要各自登录一次本地音乐库则是导入文件夹后自动建索引索引存在本地文件内容不上传。Web 版填好.env。自托管时唯一必填项是SYNC_TOKEN至少 8 位用下面命令生成随机串填进去openssl rand -hex 32 # 生成 SYNC_TOKEN 用的随机字符串AI 主题相关配置可以留空不影响播放音乐。跨设备同步主题后在 Folia「设置 → 连接与集成」填入服务端地址和SYNC_TOKEN即启用同步。Web 版如何跑起来Docker Compose新建一个空目录把仓库里的deploy/docker/compose.yaml和deploy/docker/.env.example放进去后者改名为.env字段含义逐行有注释完整说明见 deploy/docker/README.md。按上一节生成并填入SYNC_TOKEN确认FOLIA_IMAGE_NAMESPACE不为空缺失时 Compose 会直接拒绝启动。校验配置并启动--wait会等全部健康检查通过才返回docker compose config docker compose up -d --wait # 校验配置、拉取镜像并启动全栈浏览器打开http://服务器IP:18080进 Web 首页Sync Server 的健康检查地址是http://服务器IP:13000/health。做完应看到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 等标签页和搜索框。进入任意一首歌能正常播放全屏歌词动画出现。出问题时的排查方向现象先判断什么先做动作定位资料网盘里找不到自己平台的包网盘只有 Windows 与 Apple silicon 两种回 Releases 页面取对应平台安装包前置检查第 1 条AUR 构建卡在下载步骤多半是网络问题放弃 AUR改用便携包手动部署packaging/aur/folia-major-bin/PKGBUILD可核对依赖清单macOS 提示应用已损坏未签名应用被 Gatekeeper 拦截重新安装后再次执行xattr命令docs/desktop/macos-app-damaged.mdLinux 桌面快捷方式不出现占位符未替换或未标记可信检查.desktop的Exec/Icon是否已换成绝对路径packaging/linux/README-LINUX.txtLinux 启动后黑屏、透明度模糊异常或 GPU 崩溃图形路径问题不是装坏了用下面命令强制软件渲染后再启动同上文档的Linux 图形兼容性一节Web 版首页能打开但导入本地目录不可用处于纯 HTTP 而非 HTTPS 安全上下文按 Docker README 配置反向代理与证书deploy/docker/README.mdLinux 黑屏时的两条兜底命令FOLIA_LINUX_GRAPHICS_MODEswiftshader ./folia-major # 用 swiftshader 软件渲染启动 FOLIA_LINUX_GRAPHICS_MODEsoftware ./folia-major # 仍不稳定时改用更保守的软件渲染档位X11 环境下若提示智能动感模式无可用 WebGPU可尝试FOLIA_LINUX_VULKAN1 ./folia-major --ozone-platformx11该变量只对 X11 生效原生 Wayland 下会被忽略开启反而可能让 GPU 进程崩溃。延伸资料packaging/linux/README-LINUX.txtFOLIA_LINUX_GRAPHICS_MODE、FOLIA_LINUX_VULKAN图形变量全解以及壁纸模式需 Wayland 合成器支持wlr-layer-shellGNOME 不支持的细节。docs/technical.md更新通道、安装包获取方式、开发环境与常用脚本。deploy/docker/README.mdDocker 全栈的端口、环境变量表、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/11/5 5:09:45 · 阅读 1.2k Folia 安装指南：全屏歌词动画播放器，从桌面到 NAS 一次跑通
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-majorFoliafolia-major是一款把歌词渲染成全屏动画的音乐播放器桌面端基于 ElectronWeb 端基于 Node.js支持网易云、QQ 音乐、酷狗、Navidrome 以及本地音乐库。按本文走完后你可以在自己的电脑上装好桌面版、验收播放效果或者把 Web 版部署到服务器和 NAS 上用浏览器打开就能听歌看歌词动画。先判断你要走哪条路线Folia 不是只有装个 App一种玩法选错路线会白忙一场。先对照自己的情况你的实际情况推荐路线最终拿到的东西只想在自己电脑上听不想折腾桌面版Windows / macOS / Linux 安装包一个从应用菜单启动的播放器程序没有 PC或想让手机、电视、电脑都能用Docker 自托管 Web 版服务器/NAS 上的一个网址浏览器打开即用只想要同步服务不要整套 Web单独部署sync-server跨设备同步主题与设置的服务地址Arch / Manjaro 桌面习惯 AURAUR 的folia-major-bin包与桌面版等价但由 AUR 代劳下载和软链接桌面端能接的音乐源更多额外支持波点音乐、YouTube Music、Spotify、汽水音乐Web 端覆盖网易云、QQ 音乐、酷狗与 Navidrome。如果你的需求是本地歌曲 在线补全歌词封面桌面端优先如果是多台设备共享一个地址走 Web 版。前置检查动手前把这几件事确认掉下载渠道覆盖范围。官方网盘镜像夸克 / 百度百度提取码flia只放了 Windows 和 Apple silicon Mac 两种安装包Intel Mac、Linux 都不在网盘里只能去项目 Releases 页面取对应平台的包。系统依赖。Docker 路线要求 Docker Engine 24 及以上和 Compose v2AUR 路线要求先装好yay或paru且系统具备alsa-lib、gtk3、libxss、nss依赖。浏览器环境仅 Web 版。本地音乐目录的导入依赖浏览器的 File System Access API需要桌面版 Chromium 系浏览器且该能力只在 HTTPS 安全上下文里可用局域网 IP 的纯 HTTP 下会缺失。版本预期。仓库package.json当前版本为 0.7.25AUR 包folia-major-bin目前停留在 0.1.4落后较多AUR 用户要有这个心理准备。桌面端安装按系统各走各的Windows网盘或 Releases 取安装器从项目 Releases 页面下载 Windows 安装包国内网络慢就改用网盘镜像夸克或百度提取码flia。下载前对一眼网盘里的版本号与最新 release明显滞后就回 Releases 取。双击安装器走完流程在开始菜单找到 Folia 并启动。做完应看到Folia 出现在开始菜单且能正常打开主窗口。macOS拖进 Applications再解除隔离属性到 Releases 页面下载与芯片对应的.dmgarm64 或 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。LinuxArch 走 AUR其他发行版走便携包Arch / ManjaroAUR 路线yay -S folia-major-bin # 从 AUR 安装构建过程即下载 Releases 的 linux-x64 包并放入 /opt/folia-major装完后用下面的命令确认软链接已挂到/usr/bincommand -v folia-major # 预期输出 /usr/bin/folia-major包会同时装好.desktop应用项和图标从应用菜单启动即可。AUR 构建的实质是下载二进制 建软链接如果卡在下载步骤通常是网络问题不用干等直接改走下面的便携包路线。Debian / Ubuntu / Fedora 等便携包路线到 Releases 页面按发行版取包Debian 系取.debFedora / RHEL 系取.rpm其余发行版取形如folia-major-version-linux-x64.tar.gz的便携包。解压到一个固定目录把整套程序放进一个你之后不会乱动的位置mkdir -p ~/Apps/Folia tar -xzf folia-major-*-linux-x64.tar.gz -C ~/Apps/Folia # 解压便携包到固定目录便携包自带桌面项模板复制到用户级应用目录cp ~/Apps/Folia/resources/linux/folia-major.desktop ~/.local/share/applications/ # 安装桌面启动项打开复制出的.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/目录在同一个便携包内。首次启动与关键配置跳过两道引导弹窗。桌面版首启会依次出现思索模式和资料库界面选择的引导确认或跳过即可之后进入首页。登录在线音乐源。网易云、QQ 音乐、酷狗等需要各自登录一次本地音乐库则是导入文件夹后自动建索引索引存在本地文件内容不上传。Web 版填好.env。自托管时唯一必填项是SYNC_TOKEN至少 8 位用下面命令生成随机串填进去openssl rand -hex 32 # 生成 SYNC_TOKEN 用的随机字符串AI 主题相关配置可以留空不影响播放音乐。跨设备同步主题后在 Folia「设置 → 连接与集成」填入服务端地址和SYNC_TOKEN即启用同步。Web 版如何跑起来Docker Compose新建一个空目录把仓库里的deploy/docker/compose.yaml和deploy/docker/.env.example放进去后者改名为.env字段含义逐行有注释完整说明见 deploy/docker/README.md。按上一节生成并填入SYNC_TOKEN确认FOLIA_IMAGE_NAMESPACE不为空缺失时 Compose 会直接拒绝启动。校验配置并启动--wait会等全部健康检查通过才返回docker compose config docker compose up -d --wait # 校验配置、拉取镜像并启动全栈浏览器打开http://服务器IP:18080进 Web 首页Sync Server 的健康检查地址是http://服务器IP:13000/health。做完应看到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 等标签页和搜索框。进入任意一首歌能正常播放全屏歌词动画出现。出问题时的排查方向现象先判断什么先做动作定位资料网盘里找不到自己平台的包网盘只有 Windows 与 Apple silicon 两种回 Releases 页面取对应平台安装包前置检查第 1 条AUR 构建卡在下载步骤多半是网络问题放弃 AUR改用便携包手动部署packaging/aur/folia-major-bin/PKGBUILD可核对依赖清单macOS 提示应用已损坏未签名应用被 Gatekeeper 拦截重新安装后再次执行xattr命令docs/desktop/macos-app-damaged.mdLinux 桌面快捷方式不出现占位符未替换或未标记可信检查.desktop的Exec/Icon是否已换成绝对路径packaging/linux/README-LINUX.txtLinux 启动后黑屏、透明度模糊异常或 GPU 崩溃图形路径问题不是装坏了用下面命令强制软件渲染后再启动同上文档的Linux 图形兼容性一节Web 版首页能打开但导入本地目录不可用处于纯 HTTP 而非 HTTPS 安全上下文按 Docker README 配置反向代理与证书deploy/docker/README.mdLinux 黑屏时的两条兜底命令FOLIA_LINUX_GRAPHICS_MODEswiftshader ./folia-major # 用 swiftshader 软件渲染启动 FOLIA_LINUX_GRAPHICS_MODEsoftware ./folia-major # 仍不稳定时改用更保守的软件渲染档位X11 环境下若提示智能动感模式无可用 WebGPU可尝试FOLIA_LINUX_VULKAN1 ./folia-major --ozone-platformx11该变量只对 X11 生效原生 Wayland 下会被忽略开启反而可能让 GPU 进程崩溃。延伸资料packaging/linux/README-LINUX.txtFOLIA_LINUX_GRAPHICS_MODE、FOLIA_LINUX_VULKAN图形变量全解以及壁纸模式需 Wayland 合成器支持wlr-layer-shellGNOME 不支持的细节。docs/technical.md更新通道、安装包获取方式、开发环境与常用脚本。deploy/docker/README.mdDocker 全栈的端口、环境变量表、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考