Jellyfin Desktop：集成 MPV 播放器的跨平台桌面客户端

本文欲回答的核心问题：Jellyfin Desktop 是什么？它与官方 Jellyfin Media Player 有何不同？为什么值得技术爱好者尝试，以及如何在不同平台上完整构建和使用它？

Jellyfin Desktop 是一款基于 jellyfin-web 并嵌入 MPV 播放器的桌面客户端，支持 Windows、macOS 和 Linux 平台。不同于官方的 Jellyfin Media Player（媒体在独立窗口播放），它将视频直接内嵌在 jellyfin-web 界面中播放，同时支持音频直通（audio passthrough），带来更流畅、一体化的观影体验。对于追求高质量本地播放的自建媒体服务器用户来说，这是一个轻量且高度可定制的替代方案。

Jellyfin Desktop 播放界面截图
图片来源：项目官方仓库

Jellyfin Desktop 的核心优势是什么？

本节欲回答的核心问题：为什么选择 Jellyfin Desktop 而不是官方客户端或网页版？

Jellyfin Desktop 的最大价值在于将强大的 MPV 播放器与熟悉的 jellyfin-web 界面无缝结合。在实际使用场景中，当你坐在电脑前观看 4K HDR 电影时，视频不再弹出到独立窗口，而是直接嵌入网页界面，操作播放、字幕、音轨切换都保持一致性。同时，MPV 带来的硬件加速和音频直通功能，能让高比特率音频（如 Dolby TrueHD）原样输出到外接解码器，避免网页播放器常见的兼容性问题。

作者在使用过程中深刻体会到，这种内嵌式设计极大提升了桌面端的沉浸感——不再需要在浏览器和播放器之间来回切换，尤其适合大屏幕或多显示器环境。相比纯网页版，它避免了浏览器对硬件解码的支持不足；相比旧版官方客户端，它更轻量、更新更快。

下载与安装方式有哪些？

本节欲回答的核心问题：如何快速获取并安装 Jellyfin Desktop？

最简单的上手方式是直接下载预编译发布版或通过包管理器安装。

官方发布版（Windows、macOS、Linux）：
下载地址：https://github.com/jellyfin/jellyfin-desktop/releases
- macOS 用户注意：Intel 版需 macOS 12+，Apple Silicon 版需 macOS 14+。
Linux 用户推荐 Flathub：
安装命令：
```
flatpak install flathub org.jellyfin.JellyfinDesktop
```
Flatpak 版本开箱即用，隔离性好，适合不想手动管理依赖的用户。

在实际场景中，如果你只是想快速试用媒体库管理与播放功能，强烈建议先从发布版或 Flatpak 开始，几分钟即可完成部署。

如何在 Linux 上从源码构建？

本节欲回答的核心问题：在 Linux（Ubuntu/Fedora）上如何完整编译 Jellyfin Desktop 以获取最新功能或自定义？

从源码构建能让你始终使用最新代码，尤其适合贡献者或需要特定修复的用户。下面分别介绍 Ubuntu 和 Fedora 的完整流程。

Ubuntu 系统构建步骤

首先安装大量依赖：

sudo apt install autoconf automake build-essential cmake curl g++ git libasound2-dev libcec-dev libegl1-mesa-dev libfontconfig1-dev libfreetype6-dev libfribidi-dev libgl1-mesa-dev libgnutls28-dev libharfbuzz-dev libpulse-dev libsdl2-dev libtool libuchardet-dev libva-dev libvdpau-dev libx11-dev libxrandr-dev mesa-common-dev meson qml6-module-qtqml-workerscript qml6-module-qtquick-controls qml6-module-qtquick-templates qml6-module-qtquick-window qml6-module-qtwebchannel qml6-module-qtwebengine qml6-module-qtwebengine-controlsdelegates qml6-module-qtwebview qt6-base-private-dev qt6-webengine-private-dev unzip wget yasm zlib1g-dev

完整构建流程：

mkdir ~/jmp; cd ~/jmp
git clone https://github.com/mpv-player/mpv-build.git
cd mpv-build
./use-mpv-release
./update
echo -Dlibmpv=true > mpv_options
./rebuild -j$(nproc)
sudo ./install
sudo ln -s /usr/local/lib/x86_64-linux-gnu/libmpv.so /usr/local/lib/x86_64-linux-gnu/libmpv.so.1
sudo ln -sf /usr/local/lib/x86_64-linux-gnu/libmpv.so /usr/local/lib/libmpv.so.2
sudo ldconfig

cd ~/jmp/
git clone --recursive https://github.com/jellyfin/jellyfin-desktop.git
cd jellyfin-desktop
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=/usr/local/ -G Ninja ..
ninja
sudo ninja install
rm -rf ~/jmp/

在 Ubuntu 上成功编译后，你会得到一个完全集成 MPV 的客户端，能完美支持硬件加速播放大型媒体库中的视频。

Fedora 系统构建步骤

依赖安装：

sudo dnf install autoconf automake libtool freetype-devel libXrandr-devel libvdpau-devel libva-devel mesa-libGL-devel libdrm-devel libX11-devel mesa-libEGL-devel yasm alsa-lib pulseaudio-libs-devel zlib-devel fribidi-devel git gnutls-devel mesa-libGLU-devel SDL2-devel cmake wget g++ qt-devel libcec-devel qt6-qtbase-devel curl unzip qt6-qtwebchannel-devel qt6-qtwebengine-devel mpv.x86_64 qt6-qtbase.x86_64 meson.noarch ninja-build.x86_64 qt6-qtbase-private-devel mpv-libs.x86_64 mpv-devel qt6-qtdeclarative nasm libatomic libshaderc mpvqt-devel

构建命令（注意库路径差异）：

mkdir ~/jmp; cd ~/jmp
git clone https://github.com/mpv-player/mpv-build.git
cd mpv-build/
echo -Dlibmpv=true > mpv_options
echo -Dpipewire=disabled >> mpv_options  # 临时禁用 pipewire 避免段错误
./rebuild -j$(nproc)
sudo ./install
sudo mkdir /usr/local/lib/x86_64-linux-gnu
sudo ln -s /usr/local/lib64/libmpv.so /usr/local/lib/x86_64-linux-gnu/libmpv.so.1
sudo ln -s /usr/local/lib64/libmpv.so /usr/local/lib/x86_64-linux-gnu/libmpv.so
sudo ldconfig

cd ~/jmp/
git clone --recursive https://github.com/jellyfin/jellyfin-desktop.git
cd jellyfin-desktop/
mkdir build
cd build/
cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=/usr/local/ ..
make -j$(nproc)
sudo make install

作者反思：Fedora 上手动创建符号链接的步骤虽然稍显繁琐，但这正是 Linux 发行版多样性的体现——理解这些差异能让我们更深刻地掌握系统库管理。

如何在 Windows 上构建？

本节欲回答的核心问题：Windows 用户如何从源码编译 Jellyfin Desktop？

Windows 构建门槛较高，主要因为需要安装多个大型开发工具，但完成后可获得原生安装包。

所需工具：

CMake（建议 3.20+，安装时勾选添加到 PATH）
Ninja（放入构建目录）
Qt 6（安装时选择 MSVC 2019 64-bit 和 Qt WebEngine）
Visual Studio 2019 Build Tools
libmpv 开发文件（从 SourceForge 下载，解压到构建目录的 mpv 子文件夹，注意重命名和移动文件）
WiX Toolset v3.11（用于打包）

所有命令在 Git Bash 中执行：

git clone --recursive https://github.com/jellyfin/jellyfin-desktop
cd jellyfin-desktop
mkdir build
cd build

然后在“x64 Native Tools Command Prompt for VS 2019”中执行：

set PATH=%PATH%;C:\Program Files (x86)\WiX Toolset v3.11\bin
cmake -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=output -DCMAKE_MAKE_PROGRAM=ninja.exe -DQTROOT=C:/Qt/6.x.x/msvc2019_64 -DMPV_INCLUDE_DIR=mpv/include -DMPV_LIBRARY=mpv/libmpv-2.dll -DCMAKE_INSTALL_PREFIX=output ..
lib /def:mpv\mpv.def /out:mpv\mpv.dll.lib /MACHINE:X64
ninja
ninja windows_package

成功后会在 output 目录生成安装包。这套流程适合希望深度定制 Windows 版的用户，例如添加特定补丁。

macOS 构建指南

本节欲回答的核心问题：macOS 用户如何快速编译 Jellyfin Desktop？

macOS 构建相对简洁，得益于 Homebrew。

首先安装 Qt 6（记得勾选 Qt WebEngine），然后：

brew install mpv ninja qt

git clone --recursive https://github.com/jellyfin/jellyfin-desktop.git
cd jellyfin-desktop

cmake -B build -G Ninja -DUSE_STATIC_MPVQT=ON
cmake --build build

构建完成后即可运行。作者感叹：macOS 上的简洁命令行体验，让人重新爱上 Unix 风格的开发流程。

macOS 上运行的媒体播放器界面
图片来源：Unsplash（示例媒体中心场景）

配置与日志文件位置

本节欲回答的核心问题：如何找到配置文件和日志以进行调试或个性化设置？

主配置文件名为 jellyfin-desktop.conf，还可添加 mpv.conf 直接配置 MPV。

位置如下：

平台	配置目录	日志目录
Windows	`%LOCALAPPDATA%\Jellyfin Desktop\`	`%LOCALAPPDATA%\Jellyfin Desktop\logs`
Linux	`~/.local/share/jellyfin-desktop/`	`~/.local/share/jellyfin-desktop/logs/`
Linux (Flatpak)	`~/.var/app/org.jellyfin.JellyfinDesktop/data/jellyfin-desktop/`	同上
macOS	`~/Library/Application Support/Jellyfin Desktop/`	`~/Library/Logs/Jellyfin Desktop/`

在实际调试中，查看日志是定位播放问题的最快方式，例如音频设备切换失败时直接检查日志能快速定位。

如何开启 Web 调试工具？

本节欲回答的核心问题：开发或调试界面时如何使用浏览器开发者工具？

启动客户端时添加参数：

--remote-debugging-port=9222

然后在 Chrome 或 Chromium 中访问 chrome://inspect/#devices，确保已配置发现网络目标并添加 localhost:9222。

这一功能对前端开发者尤为宝贵——你可以像调试普通网页一样检查 jellyfin-web 的元素、性能和网络请求。

许可证与已知问题

Jellyfin Desktop 采用 GPL v2 许可证，依赖许可证汇总在 resources/misc/licenses.txt 中，也可运行时使用 --licenses 参数查看。

已知问题：如果自行编译 MPV，需要禁用 pipewire，否则可能导致段错误。这点在 Fedora 构建中已特别注明。

实用摘要 / 操作清单

快速上手清单：

优先尝试官方 Releases 或 Flatpak 安装。
如需最新功能，从源码构建（参考对应系统步骤）。
配置位于标准用户数据目录，可直接编辑 jellyfin-desktop.conf 或添加 mpv.conf。
调试界面问题时使用 --remote-debugging-port=9222。
查看日志快速定位问题。

一页速览（One-page Summary）

Jellyfin Desktop = jellyfin-web + 嵌入式 MPV 播放器
核心优势：内嵌播放、音频直通、跨平台
推荐安装：GitHub Releases / Flathub
构建关键：先编译 libmpv，再构建客户端
配置/日志：各平台标准用户目录
调试：远程调试端口 9222
许可证：GPL v2

常见问答（FAQ）

Jellyfin Desktop 和官方 Jellyfin Media Player 有什么区别？
Jellyfin Desktop 使用 jellyfin-web 界面，媒体内嵌播放；官方客户端媒体在独立窗口播放。
音频直通（passthrough）是否默认开启？
是的，得益于 MPV，支持 Dolby TrueHD、DTS-HD 等格式直通。
macOS 上 Intel 和 Apple Silicon 有何要求？
Intel 版需 macOS 12+，Apple Silicon 版需 macOS 14+。
Linux 上为什么有时需要禁用 pipewire？
当前自编译 MPV 时启用 pipewire 可能导致段错误，建议临时禁用。
如何查看依赖许可证？
运行程序时添加 --licenses 参数，或查看 resources/misc/licenses.txt。
配置文件叫什么名字？可以配置 MPV 吗？
主配置为 jellyfin-desktop.conf，可在同一目录添加 mpv.conf 配置 MPV。
如何开启浏览器开发者工具调试界面？
启动时添加 --remote-debugging-port=9222，然后在 Chrome 的 chrome://inspect 访问。
Windows 构建为什么需要 WiX Toolset？
用于生成 Windows 安装包（ninja windows_package 目标）。

Jellyfin Desktop深度评测：内嵌MPV播放，一键解锁你的本地影院级体验！