DistroAV 插件提示 NDI Runtime 缺失？3 个梯度 7 个错误码，一篇讲透修复全流程

DistroAV 插件提示 NDI Runtime 缺失？3 个梯度 7 个错误码，一篇讲透修复全流程

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

装好 OBS 后满心欢喜地加装 DistroAV 插件（也就是当年大名鼎鼎的 OBS-NDI），结果一启动，屏幕上直接弹出一句 "NDI Runtime 未找到"，紧接着日志里躺着一行ERR-404 - NDI library not found。相信很多第一次接触网络视频传输的朋友都在这堵墙上撞过。DistroAV 就是帮 OBS 实现 NDI 音视频传输的开源插件，通俗讲，它让 OBS 的画面能在局域网内"像有线电视一样"发给其他设备。而 NDI Runtime 是它的"发动机零件"——没有它，插件只能空转。这篇文章就围绕NDI Runtime 缺失与版本不兼容修复展开，从最省事的官方安装，到进阶手动部署，再到高手级的源码级排障，帮您一步步把发动机装回去。

先看清问题：NDI Runtime 相关的 7 个错误码

DistroAV 启动时会对 OBS 版本、NDI 库、NDI 版本依次做检查，任何一环不过关都会弹窗并写入日志。把错误码按严重程度排个序，您一眼就能定位自己属于哪一类：

DistroAV 的传输链路建立在 NDI Runtime 之上，Runtime 缺失时整条链路都无法建立。

您可以在 OBS 的日志文件里搜索ERR-字样来确认具体编号，也可以直接看弹出的提示框。下面按"从易到难"三个梯度给出修复方案，请对号入座。

入门级：走官方渠道，三分钟装回正确版本

对于绝大多数用户，NDI Runtime 缺失只是"装了个半成品"。DistroAV 官方已经给各平台准备了干净的安装方式，无需任何手工操作。

Windows

winget install --exact --id DistroAV.DistroAV

macOS

brew install --cask distroav/distroav/distroav

Linux（Flatpak 通用方案）

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

Ubuntu/Debian 系

sudo apt install distroav

📌 官方要求很明确：NDI Runtime ≥ 6.3.0，OBS ≥ 31.1.1（插件要求 Qt 6）。这两个版本底线定义在源码的 src/plugin-main.h 里，任何低于底线的组合都会被 ERR-424 / ERR-425 拦下。

预期结果：安装完成后重启 OBS，日志出现obs_module_load: NDI library initialized和NDI Library Version detected: 6.x.x，不再弹窗。

注意事项：若您此前用过旧版 OBS-NDI，务必先卸载干净再装新版本，两个插件同名模块同时存在会互相打架（详见后文误区部分）。

进阶级：手动部署 NDI Runtime，覆盖"装不上"的情况

有些场景下官方渠道不可用：比如 Linux 发行版太老没有对应包、离线环境、或是 Flatpak 沙箱权限受限。这时候就需要手动把 NDI Runtime 放到插件能找到的位置。

关键知识：插件到底去哪里找 NDI 库？

DistroAV 按顺序扫描以下路径（逻辑见 src/plugin-main.cpp 的load_ndilib()）：

• 环境变量NDILIB_REDIST_FOLDER指向的目录（最高优先级）
• /usr/lib、/usr/lib64、/usr/local/lib（Linux/macOS 通用）
• /app/plugins/DistroAV/extra/lib（Flatpak 专用）

所以"手动安装"的本质，就是让libndi.so出现在上面任一目录里。项目仓库里其实已经备好了自动化脚本 CI/libndi-get.sh，它负责下载 NDI SDK 并解压：

# 下载并解压 NDI SDK（不含安装） ./CI/libndi-get.sh # 追加 install 参数：复制库文件到 /usr/local/lib 并刷新缓存 ./CI/libndi-get.sh install

脚本执行install时会做两件关键事：

1. 把libndi.so系列文件复制到/usr/local/lib，并运行ldconfig刷新动态库缓存；
2. 创建兼容软链接libndi.so.5 → libndi.so.6，让老插件也能用上新库。

装完验证一下：

ldconfig -p | grep ndi

能看到libndi.so.6相关的输出即代表系统层面已就位。如果您在用 Flatpak 版 OBS，则需把库手动放进/app/plugins/DistroAV/extra/lib，或给沙箱授予额外的文件访问权限。

macOS 用户：将 NDI Runtime 安装到/usr/local/lib后，可用 tools/install-macos.sh 完成插件本体部署——该脚本会把构建产物复制到~/Library/Application Support/obs-studio/plugins/。Windows 用户则可借助 tools/install-windows.ps1（需以管理员身份运行）把插件部署到C:\ProgramData\obs-studio\plugins\distroav。

高手级：读懂检查逻辑，用命令行参数精准排障

如果到了这一级问题还没解决，说明环境里藏着"看不见的手"。此时与其瞎猜，不如先看懂插件的检查顺序，再用它自带的调试开关定位。

检查链路（对应 src/plugin-main.cpp 第 382~455 行）：

1. 加载 NDI 库（失败 → ERR-401 / ERR-404）；
2. 调用initialize()初始化（失败 → ERR-406，通常是 CPU 指令集不满足）；
3. 解析版本号并和 6.3.0 比对（不达标 → ERR-425）。

其中第三步还会把检测到的版本号原样写进日志：NDI Library Version detected: 5.0.0。看到这句，问题就锁定在"装的是老版本"上，换新版 Runtime 即可。

DistroAV 内置的调试参数（在启动 OBS 时以命令行附加，定义见 src/config.cpp）：

⚠️高危警告：--distroav-check-ndilib-ignore会绕过 6.3.0 的版本底线，让插件在旧版 NDI 上强行运行。源码注释明确写着这"可能导致不稳定或崩溃"，仅限开发测试环境使用，生产环境请勿开启。同样的道理也适用于--distroav-check-obs-ignore。

使用方式示例：

OBS_LOG_LEVEL=debug obs --distroav-log-level=verbose

然后查看日志里load_ndilib:开头的每一行——它会逐条列出"尝试了哪个路径、成功还是失败"，这是定位"库装对了位置没"的最快方法。

常见误区：这四个坑，踩一个就前功尽弃

❌ 错误做法：装了插件就以为 NDI Runtime 也装好了很多新手只安装了 DistroAV 插件本体，却忘了它依赖独立的 NDI Runtime。插件和 Runtime 是两个独立软件包，前者是"电视机"，后者是"信号源"。✅ 正确做法：确认 NDI Runtime 单独安装且版本 ≥ 6.3.0，再谈其他。

❌ 错误做法：旧版 OBS-NDI 和新版 DistroAV 共存两者注册了同名滤镜和源类型，会互相覆盖、加载时双双报错。✅ 正确做法：彻底卸载旧插件（Windows 到"控制面板 → 程序和功能"清理，macOS 删除~/Library/Application Support/obs-studio/plugins/下 distroav 与 obs-ndi 相关目录）后只保留其一。

❌ 错误做法：看到 ERR-425 就盲目升级，不先看检测到的版本日志里明明写着NDI Version detected: 5.0.0，说明系统里躺着一个旧 Runtime，装再新的插件也白搭。✅ 正确做法：先删旧再装新，避免多版本并存（Linux 下尤其注意/usr/local/lib里是否残留旧libndi.so.*）。

❌ 错误做法：系统是 32 位系统却硬上 64 位 RuntimeNDI SDK v6 只提供 64 位库，老旧的 32 位系统会直接触发 ERR-406（初始化失败）。✅ 正确做法：确认 OBS 为 64 位且 CPU 支持 SSE4.1 以上指令集（NDI 官方要求）。

成果验收：五步确认"真的修好了"

修复完成后，别急着关掉 OBS，按下面的清单逐项打勾：

• 启动 OBS，不再弹出"NDI Runtime 未找到"或错误码对话框
• 日志出现obs_module_load: NDI library initialized ('6.x.x')且无ERR-4xx记录
• 日志最后一行检查通过提示：NDI library version detected (6.x.x) is compatible
• 顶部菜单出现"工具 → NDI 输出设置"选项
• 场景来源里能添加"NDI 源"，且能扫描到局域网内的 NDI 设备

最后一项是关键中的关键——它验证的不只是"库能加载"，而是整条传输链路真正打通。如果源能添加但扫不到设备，请回到网络层检查：防火墙是否放行 NDI 使用的端口、设备是否处于同一网段（可参考 Linux 下对 avahi/mDNS 的放行设置）。

进阶扩展：让传输更稳的三个小技巧

问题解决后，不妨再往前走一步，让 NDI 传输质量上一个台阶：

1. 调整系统网络缓冲（Linux 示例），降低高码率下的丢包率：

sudo sysctl -w net.core.rmem_max=268435456 sudo sysctl -w net.core.wmem_max=268435456

2. 优先使用硬件编码：在 OBS 输出设置中启用 NVENC / QuickSync 等硬件编码器，把宝贵的 CPU 留给画面处理，延迟和占用都能明显改善。
3. 善用 NDI 滤镜：DistroAV 的"NDI 滤镜"功能（即独立输出）可以把单个来源或场景单独推流，适合"多机位分工推送"的场景，比整屏输出更灵活。

长效维护：让问题不再复发

NDI Runtime 缺失这类问题大多源于"版本断层"，养成三个习惯就能长期安稳：

• 每月检查一次版本：确认 NDI Runtime 与 OBS 都在官方推荐区间（见 README.md 的 Requirements 一节）；
• 升级前先清理：安装新版本前，先卸载旧 Runtime 和旧插件，避免多版本残留；
• 备份配置：将 OBS 的插件配置目录备份好，重装后可一键恢复，不必重新调参。

结语

回到开头的场景——当那句"NDI Runtime 未找到"再次弹出时，您已经不再需要发帖求助：翻一翻日志里的错误码，对照本篇的三梯度方案，从官方安装到手动部署再到源码级排查，总有一条路能走通。DistroAV 的报错虽然看着吓人，但设计得相当克制且有序：7 个错误码、一套明确的检查链路、若干排障开关，把"哪里坏了"写得清清楚楚。这也是开源项目的可爱之处——把排障能力也一并开源给了用户。装好之后，别忘了去"工具 → NDI 输出设置"里体验一把跨设备的低延迟传输，那才是这个插件真正的价值所在。

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