装完DistroAV却找不到NDI Source？NDI Runtime缺失的4类场景与彻底排查方案

装完DistroAV却找不到NDI Source？NDI Runtime缺失的4类场景与彻底排查方案

【免费下载链接】obs-ndiDistroAV (formerly OBS-NDI): NDI integration for OBS Studio项目地址: https://gitcode.com/gh_mirrors/ob/obs-ndi

打开OBS Studio，想在"来源"面板里添加NDI Source开始直播，翻遍整个列表却一无所获——这是DistroAV（原OBS-NDI）用户安装后最常遇到的尴尬局面。这个插件是OBS实现NDI网络音视频传输的核心组件，但它的功能能否启动，完全取决于系统里有没有装好NDI Runtime。本文不按"第一步到第五步"的老套路走，而是直接给你一张症状速查表，再按Windows、macOS、Linux三类场景分路给出解法，最后附一份验证清单，让你一次排查到位。

症状速查表：先对号入座再动手

DistroAV在加载失败时，会在OBS日志里写下一个形如ERR-xxx的错误码，并在界面弹出提示框。根据错误码直接定位问题，比瞎试高效得多：

打开日志的方法是：OBS菜单栏"帮助 → 日志文件 → 查看日志文件"。如果嫌日志刷屏，可以在启动OBS的命令后加上--distroav-debug参数，插件会输出更详细的过程信息。

先说清楚：为什么一个"Runtime"能卡死整个插件

很多人把插件当作"装进去就能用"的独立软件，但DistroAV不是。它的工作方式更像微信与网卡驱动的关系：插件负责把OBS画面打包成NDI协议数据（相当于微信负责把消息发出去），而NDI Runtime才是真正干活的下层组件（相当于网卡驱动负责把数据真正送上网络）。驱动没装，微信界面再正常也发不出消息；Runtime缺失，DistroAV的NDI Source、NDI Output、NDI Filter自然一个都注册不进来。

DistroAV插件本体对依赖有两个硬性要求：OBS版本≥31.1.1，且NDI Runtime版本≥6.3.0。同时它只提供64位版本，所以系统里的Runtime也必须是64位。理解了这个依赖关系，下面三类场景的解法就顺理成章了。

场景一：Windows用户装好Runtime，插件仍报ERR-401/404

这是最常见的一类。排查顺序请严格按下面来：

1. 检查Runtime到底装没装上。打开"设置 → 应用 → 已安装的应用"，搜索"NDI"，确认存在且版本号≥6.3.0。很多安装包只是解压了文件却没有写入系统注册表，这种情况下OBS是感知不到的。

2. 检查位数是否一致。在"系统信息"里确认你的Windows是64位。如果误装了32位Runtime，配合64位OBS就会出现ERR-402或ERR-405这类"文件在但用不了"的报错。卸载后重装64位版本即可。

3. 用管理员权限重装一遍。删除现有Runtime，右键安装包选择"以管理员身份运行"，保持默认选项走完。装完后必须重启电脑，让系统服务和环境变量真正生效。没有管理员权限时，Runtime的系统组件注册往往会被静默跳过——表面上"安装成功"，实际什么都没写入。

4. 检查环境变量兜底。如果以上都正常仍报ERR-404，可以在系统环境变量中新增NDILIB_REDIST_FOLDER，值指向NDI库文件（Processing.NDI.Lib等）所在目录。插件在查找NDI库时，会优先读取这个变量指定的位置（对应源码load_ndilib()里的查找逻辑）。

插件本体用官方命令安装即可：

winget install --exact --id DistroAV.DistroAV

场景二：macOS用户提示找不到库文件

macOS版DistroAV默认会在/usr/local/lib等固定目录下寻找NDI库。如果你用Homebrew安装插件，却只装了插件本体、漏装了Runtime，就会在启动时看到ERR-404弹窗。

先确认Runtime是否真的进了系统。NDI Runtime安装包在macOS上会安装到/usr/local/lib，你可以打开"访达 → 前往 → 前往文件夹"，输入/usr/local/lib，看看里面有没有以libndi开头的文件。没有就补装Runtime。

插件本体通过Homebrew安装：

brew install --cask distroav/distroav/distroav

如果你是Apple Silicon（M1/M2/M3）机型，还要额外确认两件事：OBS必须是原生ARM版或Rosetta兼容版，且Runtime也装了对应架构。架构混搭是macOS上ERR-402的常见来源。另外macOS对第三方组件权限卡得很严，若首次启动弹窗询问是否允许加载，一定要选"允许"，否则库会被系统静默拦截。

场景三：Linux/Flatpak用户：插件能加载却搜不到设备

Flatpak版的DistroAV安装后，NDI Source、NDI Output都能出现，但局域网里一个设备都发现不了——这不是Runtime的问题，而是沙箱权限的问题。Flatpak把插件关在"隔离箱"里运行，默认不开放网络服务发现的权限，NDI靠mDNS（Avahi服务）在局域网内广播和发现设备，权限被挡自然全盲。

安装与授权两条命令缺一不可：

flatpak install com.obsproject.Studio com.obsproject.Studio.Plugin.DistroAV sudo flatpak override com.obsproject.Studio --system-talk-name=org.freedesktop.Avahi

第二条命令是给OBS放行访问Avahi服务（负责局域网设备发现）的权限。执行完这条后，重启OBS再刷新NDI设备列表。Flatpak安装的插件会在/app/plugins/DistroAV/extra/lib下寻找NDI库，所以Debian系用户如果从源码编译安装，还需要自己把Runtime的库文件放到系统库目录（/usr/lib或/usr/lib64）中。

场景四：升级后反而报错：旧版obs-ndi残留冲突

2024年6月起，OBS-NDI正式更名为DistroAV。如果你之前装过旧版obs-ndi插件，升级时没有彻底卸载干净，启动OBS就会弹出ERR-403：插件检测到系统里同时存在新旧两个插件，为避免冲突直接拒绝加载。

解法很明确：把旧版obs-ndi完整卸载。重点检查两个位置：一是插件安装目录里的obs-ndi相关文件（Windows通常在OBS安装目录的obs-plugins/64bit/下，macOS在/Library/Application Support/obs-studio/plugins/），二是OBS数据目录里残留的配置。删干净后重启OBS，ERR-403即消失。改版后新老插件的功能完全一致，不存在"新旧搭配更香"的说法。

装完不等于能用：5分钟验证清单

排完障后，用这张清单逐项确认，全绿才算真正收工：

• 启动OBS无任何ERR弹窗，日志中无ERR-40x/42x记录
• "来源"面板点"+"，列表中出现"NDI Source"
• "工具"菜单出现"NDI输出设置"入口
• 来源右键菜单中出现"NDI Filter"（滤镜效果）
• 添加NDI Source后能搜到局域网内其他NDI设备
• 在其他设备上能看到本机发布的NDI源

让NDI更好用的三个进阶设置

插件跑通只是开始，进入NDI Source的高级属性，你会看到几个直接影响画质和性能的参数，它们对应源码中的定义：

#define PROP_SOURCE "ndi_source_name" // 选择要接收的NDI源 #define PROP_BANDWIDTH "ndi_bw_mode" // 带宽模式：高画质或低延迟 #define PROP_SYNC "ndi_sync" // 音视频同步策略 #define PROP_FRAMESYNC "ndi_framesync" // 帧同步开关，画面撕裂时开启 #define PROP_HW_ACCEL "ndi_recv_hw_accel" // 硬件加速，高分辨率下显著降CPU占用 #define PROP_YUV_RANGE "yuv_range" // 色彩范围：Limited/Full #define PROP_YUV_COLORSPACE "yuv_colorspace" // 色彩空间：Rec.601/709/2020

如果CPU占用率居高不下，优先打开硬件加速；若画面出现卡顿或撕裂，检查帧同步和带宽模式；做专业调色时，务必让NDI源的色彩空间与OBS项目设置保持一致，否则颜色会偏。想了解每个参数的具体作用，源码在仓库的src/目录（ndi-source.cpp、main-output.cpp等文件），README.md里有完整的安装说明和需求清单。

收尾：一套可复用的排查思路

最后把这些经验沉淀成一套通用方法，以后任何插件出问题都能套用：先看错误码定位层次（依赖缺失还是版本冲突），再按"本体 → 依赖 → 权限"的优先级逐层排除，最后用验证清单确认收尾。

如果你还想深入：学习NDI的色彩科学和带宽管理、用OBS脚本自动化切换NDI源、搭建多机位NDI制作系统，都是很好的进阶方向。排查中遇到本文没覆盖的报错，把你日志里的ERR错误码记下来，去插件官方文档的错误码对照表里查一下，多数问题都能找到现成答案。

设备之间通过NDI握手的那一刻，你会发现之前折腾安装的一切都值得。放心去试吧，你已经把最容易踩的坑都摸清了。

【免费下载链接】obs-ndiDistroAV (formerly OBS-NDI): NDI integration for OBS Studio项目地址: https://gitcode.com/gh_mirrors/ob/obs-ndi