DistroAV 报错别慌！NDI Runtime 缺失与版本不兼容的完整修复手册

DistroAV 报错别慌！NDI Runtime 缺失与版本不兼容的完整修复手册

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

周五晚上十点，你刚把 DistroAV——那个给 OBS Studio 加装 NDI 跨设备传输能力的插件，前身叫 OBS-NDI——装好，正准备跟客厅的电脑互联推流。结果重启 OBS 的瞬间，弹窗直接给你泼了盆冷水："Error-401：NDI library failed to load"，或者更扎心的"Error-425：需要 NDI Runtime 6.3.0 及以上"。

先别急着卸载重装。这种"插件装好了却哑火"的情况，九成以上都是同一个原因：NDI Runtime 没到位，或者版本太旧。这篇文章不堆命令、不抄说明书，就带你从"它到底是啥"一路走到"彻底修好"，每一步都能照做。

先对号入座：NDI Runtime 缺失、版本不兼容，一张表分清

不急着动手，先给你一张全景地图。DistroAV 的报错看起来五花八门，其实每个都有编号，藏在 OBS 日志里。按编号对号入座就行：

读这张表有个速记口诀：401 是"没装"，425 是"太旧"，406 是"硬件不让"。把这句话记在心里，你排查时能省一半时间。

第一问：装个插件，为什么还要再装一个 NDI Runtime？

一句话说清：DistroAV 是"喊话的"，NDI Runtime 是"翻译机"。

DistroAV 做的事，说人话就是把 OBS 里的画面和声音打包成 NDI 信号，在局域网里发给其他装了 NDI 的设备。可 NDI 这套协议不是 OBS 发明的，它来自 NDI 官方提供的一套底层运行库，也就是NDI Runtime。你可以把它想象成一台翻译机：DistroAV 负责把你 OBS 里的内容"喊"出去，Runtime 负责把这声喊翻译成所有 NDI 设备都听得懂的"普通话"。

所以问题就清楚了：插件装好了、翻译机没装，DistroAV 一开口对方就听不懂；翻译机太旧（比如停在 5.0 版），一开口就是"方言"，照样对不上。这正是"缺 Runtime"（ERR-401）和"版本不兼容"（ERR-425）的本质区别。

第二问：怎么确认自己撞上了哪个错误码？翻日志就行

别靠猜，让日志说话。启动 OBS 后，依次打开帮助 → 日志文件 → 查看日志文件，然后在日志里搜两个关键词：NDI Library或ERR-。真实情况全写在里面。

日志里你会看到这样的几行，对照着认：

• NDI Library Version detected: 6.5.2—— 插件实际加载到的版本号
• NDI library version detected (...) is compatible—— 版本过关
• ERR-401 - NDI library failed to load—— 没找到库
• ERR-425 - ... requires at least NDI version 6.3.0—— 版本太旧

看完日志，你就知道自己属于哪一格了，顺着下一问往下走。

小提示：日志里那一行NDI Library Version detected是插件真实加载到的版本，比你去系统设置里翻安装记录更靠谱。之后每次修完，都回这里看数字。

第三问：明明装了 Runtime，为什么还报版本不兼容？

如果你日志里已经是 ERR-425，说明 Runtime 在，但卡在了两个版本门槛上：

• NDI Runtime ≥ 6.3.0：这是 DistroAV 写死的最低要求，定义在源码src/plugin-main.h的PLUGIN_MIN_NDI_VERSION里，版本检查逻辑在src/plugin-main.cpp。
• OBS ≥ 31.1.1（Qt6 版本）：OBS 本身太老，插件同样起不来。

版本数字对不上，先升级。但版本太老还有一个被忽视的元凶——系统里赖着一个旧版本没走干净。Windows 上打开"设置 → 应用"，把所有带 NDI 字样的组件全部卸载，再装新的；macOS 上如果之前手动装过，去/Library/NDI/目录看看有没有旧文件残留。原则很简单：先清后装，装完重启。这一步看着粗暴，但对治 ERR-425 往往立竿见影。

第四问：Windows、macOS、Linux 分别怎么修？

插件本身没问题的话，就轮到"翻译机"归位了。三个平台各说各话，照着做就行。

Windows：

1. 用官方渠道重装插件：winget install --exact --id DistroAV.DistroAV
2. 去 NDI 官网下载 Runtime 安装包（项目代码里的PLUGIN_REDIRECT_NDI_REDIST_URL指向的就是它）
3. 安装时勾选"为所有用户安装"，装完重启一次电脑，让环境变量生效

macOS：

1. 官方渠道：brew install --cask distroav/distroav/distroav
2. 从官网下载 macOS 版 Runtime，拖入 Applications
3. 顺手验证一下：打开终端，看看/Library/NDI/目录下有没有新装的运行时文件

Linux：

1. Ubuntu 系直接sudo apt install distroav，依赖通常会自动带进来
2. 通用方案走 Flatpak，运行时一般也一并处理妥当
3. 如果依然报缺库，直接查官方安装文档里针对你发行版的说明，别硬搜网上的"万能解法"

装好 Runtime 后回日志看NDI Library Version detected那一行，只要数字 ≥ 6.3.0，并且出现 "is compatible"，这一关就算过了。

第五问：修好没有？六个勾帮你验收

修没修好，别凭感觉，照这份清单打勾：

• 启动 OBS 后，不再弹出 ERR-401 / ERR-425 错误框
• 日志里能搜到NDI Library Version detected，且版本号 ≥ 6.3.0
• 日志里出现NDI library version detected (...) is compatible
• "工具"菜单里能看到"NDI 输出设置"
• 来源面板右键能添加"NDI 源"，并能扫到局域网里的其他 NDI 设备
• 双向传输都通：你能看到别人，别人也能看到你的输出

六个勾全打上，恭喜，你的 DistroAV 满血复活。如果卡在某个勾上，多半是防火墙或网络配置的问题，那就是另一个话题了——但至少，"Runtime 缺失"这个大坑你已经填平了。

快问快答：六个高频疑问一次答清

Q1：怎么知道我装的 NDI Runtime 是哪个版本？Windows 去"设置 → 应用"里看已装组件；更准的是看 OBS 日志里的NDI Library Version detected一行，那是插件真实加载到的版本。

Q2：升级 OBS 之后插件突然报错，为什么？DistroAV 要求 OBS ≥ 31.1.1（Qt6）。如果 OBS 太老，或追了太激进的测试版，兼容性就会出问题。回退稳定版或同步升级插件都值得一试。

Q3：我只想在局域网里两台电脑互传，也必须装 Runtime 吗？必须。Runtime 是 NDI 协议本身的地基，跟传多远没关系——翻译机不能因为距离近就不装。

Q4：装了两个不同来源的插件，会打架吗？会。老版 OBS-NDI 和 DistroAV 同名文件共存，是报错重灾区。卸载干净、只留官方渠道一个版本，比什么都管用。

Q5：Linux 上怎么判断是插件问题还是系统问题？先看 OBS 日志里的错误码：ERR-401 说明系统缺 NDI 运行时或路径没对上，ERR-425 是版本太低。结合发行版包管理器装依赖，一般都能解决。

Q6：跳过版本检查能用吗？能"开"但强烈不建议。插件提供了--distroav-check-ndilib-ignore参数跳过检查、--distroav-check-ndilib-forcefail强制失败（后者用于自动化测试），参数解析在src/config.cpp。跳过检查也许能让插件"看起来能开"，但底层翻译机对不上，功能大概率残缺甚至崩溃。这是给开发者调试用的后门，普通用户请老老实实装对版本。

留给想深挖的你：源码坐标与最后叮嘱

想较真研究的话，给你几个源码坐标，看得懂就赚到，看不懂也不影响使用：

• src/plugin-main.cpp：NDI 库加载、初始化与版本检查的完整流程，ERR-401 / ERR-406 / ERR-425 的日志都在这里输出
• src/plugin-main.h：最低版本要求定义在PLUGIN_MIN_NDI_VERSION，即 "6.3.0"
• src/forms/output-settings.cpp：设置界面里会实时显示检测到的 NDI 版本是否达标
• tools/install-windows.ps1和tools/install-macos.sh：从源码自己编译时，负责把产物一键部署进 OBS 插件目录

最后叮嘱两句：只走官方渠道装插件（winget / brew / apt / Flatpak），更新后先翻一眼日志，心里记死"NDI ≥ 6.3.0、OBS ≥ 31.1.1"两个数字。只要这条地基补齐，你的 DistroAV 就能稳稳地把画面送出去——祝你今晚的流，推得又稳又顺。

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