装好 DistroAV 就弹 ERR-401、ERR-425？NDI Runtime 缺失与版本不兼容，一条龙修复实录

装好 DistroAV 就弹 ERR-401、ERR-425？NDI Runtime 缺失与版本不兼容，一条龙修复实录

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

DistroAV（前身 OBS-NDI）是给 OBS Studio 用的 NDI 集成插件，装上它，你的画面和声音就能通过局域网实时发给其他 NDI 设备。可很多人装完重启 OBS，迎来的不是流畅推流，而是弹窗上刺眼的 "Error-401: NDI library failed to load" 或 "Error-425: 需要 NDI Runtime 6.3.0 及以上"。别急着卸载重装，九成是同一个东西没到位：NDI Runtime。

周五晚上十点，弹窗先于画面到达

周五晚上十点，你终于说服自己把 DistroAV 装进了 OBS Studio，为了这一刻连推流参数都背熟了。可就在双击 OBS 图标五秒后，一个红色弹窗横在眼前：Error-401，NDI library failed to load。不信邪，重装两遍，弹窗又换成了 Error-425，提示需要 NDI Runtime 6.3.0 及以上。

这一幕我见过太多次。九成情况下，不是插件坏了，而是系统里那台"翻译机"没装、或装的是老型号。下面这篇实录，陪你把问题从头捋到尾，每走一步都有"做到什么程度算成功"的判断标准。

先把错误码地图摊开，对号入座

不急着动手，先花三分钟对号入座。DistroAV 很讲规矩，每种失败都会在弹窗和日志里留下一个带编号的错误码，以下是它的"错误码地图"：

怎么确认自己撞上的是哪个码？让日志说话：启动 OBS 后，从"帮助 → 日志文件 → 查看日志文件"打开日志，直接搜 "ERR-" 或 "NDI Library"，真实情况全写在里面。看到自己属于哪一格后，顺着下面的路线往下走就行。

翻译机原理：DistroAV 喊话，Runtime 翻译

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

插件装好了、翻译机没装，DistroAV 一开口对方就听不懂——这是"缺 Runtime"（ERR-401）；翻译机是老型号（比如 5.x），对方也听不懂——这是"版本不兼容"（ERR-425）。想清楚这一层，你就知道该修什么了：不是修插件，是修翻译机。

两个数字记牢：NDI ≥ 6.3.0，OBS ≥ 31.1.1

排查时心里要有两个底线数字，能省一半时间：

• NDI Runtime ≥ 6.3.0：这是 DistroAV 的最低要求，定义在源码src/plugin-main.h的PLUGIN_MIN_NDI_VERSION里。
• OBS ≥ 31.1.1（Qt6 版本）：太低的话，插件连功能都注册不上，报 ERR-424。

这两个数字不是拍脑袋定的，版本比较逻辑写在src/plugin-main.cpp的is_version_supported()里，插件的每次启动加载都会拿真实环境跟它们比对。记住它们，你就知道后面每一步在跟什么"对表"。

第一趟：重走官方装配线，别让整合包背锅

很多"缺 Runtime"其实是装错了来源。DistroAV 的官方安装方式分平台：

• Windows：winget install --exact --id DistroAV.DistroAV
• macOS：brew install --cask distroav/distroav/distroav
• Ubuntu 系：sudo apt install distroav
• 通用方案（Flatpak）：flatpak install com.obsproject.Studio com.obsproject.Studio.Plugin.DistroAV

如果你是从杂七杂八的"整合包"里拷进来的，很可能插件本体不完整，或者和系统里残留的旧版 OBS-NDI 冲突。先卸掉手头这个版本，走上面官方渠道重装一遍，能解决相当一部分"装完就报错"的案例。装完重启 OBS 看还报不报——不报，直接跳到最后的验证清单打勾。

第二趟：让翻译机各就各位

插件本身没问题的话，就该检查翻译机了。三个平台各说各话，跟着自己对应的那行走：

• Windows：去 NDI 官网下载 Runtime 安装包（插件源码里PLUGIN_REDIRECT_NDI_REDIST_URL指向的就是这个入口），安装时勾选"为所有用户安装"，装完重启一次电脑让环境变量生效。
• macOS：同样从官网下载 macOS 版 Runtime 并装进 Applications。装完顺手验证一下：打开终端，看看/Library/NDI/目录下有没有新装好的运行时文件（源码的库搜索路径里也包含/usr/local/lib）。
• Linux：情况最特殊。Ubuntu 用apt install distroav时依赖通常会被自动带进来；Flatpak 方案一般也把运行时一并处理妥当（库会放到/app/plugins/DistroAV/extra/lib）。如果依然报缺库，检查 NDI 库是否出现在/usr/lib、/usr/lib64、/usr/local/lib这些插件会去翻的目录里，也可以通过环境变量NDILIB_REDIST_FOLDER直接告诉插件库在哪。

装好 Runtime 后，去 OBS 日志里搜"NDI Library Version detected"，能看到插件实际加载到的版本号。只要这个数字 ≥ 6.3.0，这一关就算过了。

第三趟：请走旧房客，别让两个 Runtime 打架

版本太老最常见的原因不是没升级，而是系统里还赖着一个旧版本没走。Windows 上打开"设置 → 应用"，把所有带 NDI 字样的组件全部卸载干净再装新的；macOS 上如果之前手动装过，/Library/NDI/下的旧文件也可能残留。清理原则很简单：先清后装，装完重启。

还有一类容易忽略的"旧房客"是老插件本身：如果日志里出现ERR-403，说明系统里还检测到了旧版 OBS-NDI 插件——它的文件和 DistroAV 同名共存，是报错重灾区。把老插件卸干净、只留官方渠道一个版本，比什么都管用。这一步看着粗暴，但对治 ERR-425 往往立竿见影。

日志是 X 光片：搜这两行，就知道好没好

走到这儿如果还报错，问题就不那么"常规"了，这时候更要学会让日志说话。除了开头的 "ERR-" 之外，成功和失败的判定就藏在两行日志里：

• 失败时：日志会记录 ERR-401 / ERR-404 / ERR-425 这类编号，搜到哪个，对着前面的错误码地图看。
• 成功时：日志里会出现"NDI Library Version detected: 6.x"，紧接着还有一行"NDI library version detected (...) is compatible"。

把错误码原样记下来去搜官方知识库，比在论坛里描述"我有个插件报错"高效得多。让日志告诉你"差在哪"，而不是靠猜。

开发者留的后门，普通人别碰

最后说一个几乎只给开发者用的东西。DistroAV 提供几个命令行参数：--distroav-check-ndilib-ignore可以跳过 NDI 版本检查，--distroav-check-ndilib-forcefail则是让检查强制失败（给自动化测试用的）。参数解析逻辑在src/config.cpp的ProcessCommandLine()里。

理解这个设计你就明白：它默认是"宁可不干活，也不带病运行"。跳过检查或许能让插件"看起来能开"，但底层翻译机对不上，功能大概率还是残的，甚至可能崩。除非你在开发调试，否则这条后门不建议碰——把 Runtime 修对，永远比绕过检查省事。

满血复活六连勾

修复动作到这里基本结束，用这份清单给自己打个分：

• 启动 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 同名文件共存，是 ERR-403 报错的重灾区，卸载干净、只留一个官方版本。

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

Q6：跳过版本检查能用吗？能"开"但不建议用，功能大概率残缺甚至崩溃。这个参数是给开发测试准备的，普通用户请老老实实装对版本。

让问题不再复发的小习惯

• 只走官方渠道：插件一律用 winget / brew / apt / Flatpak 装，别图省事用整合包。
• 更新后先看日志：每次升级 OBS 或插件，重启后扫一眼有没有新的 ERR，早发现早处理。
• 心里记两个数字："NDI ≥ 6.3.0、OBS ≥ 31.1.1"，排查时能省一半时间。
• 旧版本随手清：卸载软件时把带 NDI 字样的残留一并处理，别让"旧房客"潜伏下来。

最后说两句

DistroAV 的报错框看着吓人，但本质上只是它"不愿意带病上班"的自我保护——把 NDI Runtime 这条地基补齐，剩下的路就顺畅了。想深究源码的读者，可以去看src/plugin-main.cpp（版本检查与错误码逻辑）、src/plugin-main.h（PLUGIN_MIN_NDI_VERSION等最低版本定义）、src/config.cpp（命令行参数解析），以及tools/下install-windows.ps1、install-macos.sh这两个把编译产物部署进 OBS 插件目录的脚本。想从源码自己编译的，可以git clone https://gitcode.com/gh_mirrors/ob/obs-ndi拉下来慢慢逛。要是卡在更细的坑里，比如防火墙拦了 NDI 设备发现，官方文档和项目 Wiki 里都有对应的排查章节，照着翻就行。祝你今晚的流，推得又稳又顺。

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