ZLMediaKit 在Window上本地模拟预览报错排查教程场景按start_sim.bat在 Windows 本地用FFmpeg MediaMTX ZLMediaKit模拟摄像头预览时ZLMediaKit 侧出现的各类报错、原因与解决办法。本文按启动 → 建流 API → FFmpeg/MediaMTX → 前端播放 → 释放五个阶段归类最后一节给快速定位决策树 配置核对清单。摄像头视频预览实现教程从原理到落地(ZLMediaKit flv.js Spring Boot)https://blog.csdn.net/BADAO_LIUMANG_QIZHI/article/details/163018250先看清 ZLMediaKit 返回的错误码调用 ZLMediaKit 的 HTTP API如addStreamProxy/getServerConfig时返回 JSON 里带code字段code0表示成功非 0 表示失败。常用语义不同版本数值可能略有差异以官方为准code含义典型触发0成功正常-1失败通用内部错误、流已存在等-2不支持操作/协议不支持-3无权限鉴权失败secret与config.ini [api].secret不一致-4未找到源不存在关流时streamKey写错、流已不在其他负数参数/资源等具体错误缺少必填参数、资源冲突等⚠️最重要的一条认知addStreamProxy返回code0只代表代理已创建并不代表 RTSP 源真的连上了。真正的拉流是异步进行的——源连不上时建流接口照样返回 0但前端播放会黑屏。判断源是否真连上要看ZLM 日志或/index/api/getMediaList。一、阶段一ZLMediaKit 启动报错1.1 端口被占用Bind 0.0.0.0:80 failed/ 程序闪退现象启动MediaServer.exe后控制台刷Bind 0.0.0.0:80 failed ... Address already in use随后程序退出。原因Windows 上80 端口常被 IIS / World Wide Web Publishing / 系统进程(SVCHOST) 占用也可能是 554/1935 被别的流媒体占用。解决查占用netstat -ano | findstr :80→ 看 PID任务管理器结束对应进程IIS 可iisreset /stop。更稳妥改config.ini端口避开 80[http] port8080 # 【本项实际值】本地模拟即用 8080并同步改项目application.yml的zlm.http-port8080以及前端播放地址端口。防火墙放行新端口netsh advfirewall firewall add rule nameZLM-HTTP dirin actionallow protocolTCP localport8080。1.2 找不到配置文件 /Load config failed现象启动报找不到config.ini或用了默认空配置。原因没带-c参数或工作目录不在config.ini所在目录。解决启动时显式指定cd /d D:\tools\ZLMediaKit MediaServer.exe -c config.ini脚本start_sim.bat已用cd /d %ZLM_DIR% MediaServer.exe注意它实际未带-c也能跑因为同目录默认识别config.ini。1.3 缺少运行库0xc000007b/ 缺少 VCRUNTIME / MSVCP 等 DLL现象双击MediaServer.exe报应用程序错误、缺 DLL。原因系统缺少 Visual C 运行库或下了源码版而非预编译包。解决安装Visual C Redistributable2015–2022务必从 GitHub Release 下载windows.zip/ZLMediaKit_win64预编译包而非源码压缩包。1.4 启动后无监听 / 立即退出无任何日志原因多半是端口冲突见 1.1或config.ini有非法段导致解析中断。解决先看控制台第一行日志定位用netstat -ano | findstr :8080确认是否在监听临时把config.ini换成官方默认文件排除配置问题。二、阶段二调用 API 建流报错addStreamProxy / getServerConfig2.1 getServerConfig 返回鉴权失败 / 空白 / 403现象浏览器打开http://127.0.0.1:8080/index/api/getServerConfig?secretxxx返回错误 JSON 或无数据。原因URL 里的secret与config.ini [api].secret不一致最常见或忘记带secret参数。解决确认两端完全一致改了config.ini的 secret 必须重启 ZLM 才生效不是热加载。本项目实际secret035c73f7-bb6b-4889-a715-d9eb2d1925cc且application.yml的zlm.secret必须与之相同。2.2 addStreamProxy 返回code-3无权限现象后端日志/接口返回{code:-3,...}。原因后端ZlmProperties.secret与 ZLM 的secret不一致或调用时secret参数拼错。解决核对application.yml的zlm.secretconfig.ini [api].secret重启两端。2.3 addStreamProxy 返回code-1/ 其他非 0现象建流接口返回失败但非鉴权类错误。原因流已存在幂等场景同一app/stream已建过ZLM 报资源冲突。本项目后端已做 try-catch 忽略异常、照常返回播放地址可忽略。缺少必填参数vhost/app/stream/url之一缺失。rtp_type取值非法。解决确认请求参数齐全流已存在时无需处理前端照常播放用getMediaList确认该流状态。2.4 addStreamProxy 返回0但播放黑屏高频坑现象接口code0前端却一直黑屏/转圈*.flv请求 200 但没有画面或播放器报源未找到。原因异步拉流——代理建好了但底层 RTSP 源没连上。常见根因FFmpeg 还没开始推流cam1 尚不存在MediaMTX 没启动 / 8554 未监听RTSP 地址写错本项目应为rtsp://127.0.0.1:8554/cam1源视频封装-c copy不兼容 RTSP见第四节。解决确认模拟三件套启动顺序mediamtx → ZLMediaKit → ffmpeg 推流看 ZLM 日志里是否有Failed to connect rtsp之类调/index/api/getMediaList?secretxxx看是否出现live/dev_1且readerCount0用ffprobe -rtsp_transport tcp rtsp://127.0.0.1:8554/cam1验证源有h264轨。2.5 前端播放报 CORS /Access-Control-Allow-Origin错误现象浏览器控制台红色 CORS 报错flv 请求被拦。原因前端页面与 ZLMediaKit不同源域名/端口/协议不同而 ZLM 未开启跨域。解决在config.ini打开跨域http 与 api 两段都要[http] allow_cross_domains1 # 允许 HTTP-FLV 跨域 [api] allow_cross_domains1 # 允许 API 跨域保存后重启 ZLM。本项目本地同源都是 127.0.0.1一般不触发但部署到不同端口/域名时一定要开。2.6 delStreamProxy 返回code-4未找到现象关流接口报-4 资源不存在。原因streamKey格式写错。正确格式为app/stream如live/dev_1不含.live后缀且 ZLM 文档有时写key、本项目后端用streamKey要统一。解决本项目后端封装streamKey zlm.getApp() / streamId→live/dev_1直接调 ZLM 也可写key__defaultVhost__/live/dev_1带 vhost 前缀关流前确认该流确实存在没建过自然找不到可忽略。三、阶段三FFmpeg / MediaMTX 报错源侧这些虽不是 ZLM 直接报错但会表现为 ZLM 拉不到源 → 2.4 黑屏所以一并列出。3.1 FFmpegUnknown output format rtsp/Protocol not found现象ffmpeg 推流命令直接报错退出。原因下载的 ffmpeg 构建不含 RTSP muxer某些精简版。解决换gyan.dev或BtbN的full_build完整构建解压后ffmpeg -version正常、ffmpeg -formats | findstr rtsp能看到 rtsp。3.2 FFmpegConnection refused/Could not find an AVPacket现象ffmpeg 连不上目标地址。原因MediaMTX 没启动、或 8554 没监听、或推流 URL 端口写错。解决先启动mediamtx.exeRTSP server listening on :8554netstat -ano | findstr :8554确认监听核对RTSP_URLrtsp://127.0.0.1:8554/cam1。3.3 推流进程退出 / MediaMTX 里没有 cam1现象ffmpeg 窗口闪退或停止ffprobe探测cam1失败。原因test.mp4路径不对 / 文件损坏源编码 ffmpeg 无法解码漏了-re瞬间推完导致假死。解决确认TEST_VIDEOD:\tools\test.mp4存在且可播用ffplay test.mp4自测保留-re -stream_loop -1。3.4-c copy失败封装不兼容 RTSP现象ffmpeg 报Could not find tag ...或不兼容封装错误。原因源文件封装如某些 MP4 的音频轨不能直接用 RTSP 封装。解决去掉-c copy改为转码ffmpeg -re -stream_loop -1 -i test.mp4 -c:v libx264 -c:a aac -f rtsp rtsp://127.0.0.1:8554/cam13.5 画面不循环 / 播一会儿就停现象推流只播一遍就停。原因漏了-stream_loop -1无限循环。解决确认命令含-stream_loop -1。四、阶段四前端 flv.js 播放报错4.1 黑屏一直转圈请求 200 无画面现象F12 看*.flv返回 200但video黑屏。原因见2.4——ZLM 建流成功但 RTSP 源没连上FFmpeg/MediaMTX 没就绪。解决回到第三节确认源用getMediaList看流是否真有数据。4.2 flv.js 报错Unsupported MediaDataSource/Not supported现象播放器直接报错不发起请求。原因传入的url不是http(s)://...flv格式如少了.flv后缀、或写成了 RTSP 地址。解决播放地址必须是http://play-host:http-port/app/stream.flv如http://127.0.0.1:8080/live/dev_1.flv。本项目buildFlvUrl已拼好不要手改后缀。4.3 混合内容被拦blocked:mixed-content现象HTTPS 页面下 flv 请求被浏览器拦截红字 mixed content。原因页面是https但 ZLM 播放地址是http浏览器禁止混合内容。解决开发期页面也用http访问生产给 ZLM 配 SSLconfig.ini [http].sslport 证书或前面挂Nginx 反代 HTTPSflv 走https。4.4 自动播放被浏览器拦截现象画面不自动起播需手动点。原因浏览器自动播放策略要求静音才能自动播。解决video加muted本项目VideoPreview已加muted autoplay playsinline。4.5 播放卡顿 / 延迟 3s现象画面能播但卡、延迟高。原因stashBuffer缓冲、源是主码流、UDP 拉流丢包。解决前端关闭 flv.js 大缓冲后端rtp_type0TCP 拉流源用子码流仍不够再考虑升级 WebRTC。五、阶段五释放 / 关闭报错5.1 关流无效果 / 流仍在现象关闭弹窗后getMediaList里流还在。原因delStreamProxy的streamKey写错见 2.6依赖streamNoneReaderDelayMS兜底时要等 20s 才自动断本项目配 20000ms。解决确认streamKeylive/dev_1或等待自动断流或把streamNoneReaderDelayMS调小便于调试。5.2 stop_sim.bat 关不干净现象脚本跑完仍有进程。原因taskkill按窗口标题匹配窗口标题被改过就匹配不到。解决任务管理器手动结束mediamtx.exe/MediaServer.exe/ffmpeg.exe或taskkill /f /im mediamtx.exe /im MediaServer.exe /im ffmpeg.exe。六、快速定位决策树拿到问题先问这 5 个播放黑屏/无画面 ├─ ZLM 进程在跑吗 netstat -ano | findstr :8080 │ └ 否 → 回一、启动报错修端口/配置 ├─ getServerConfig 返回 JSON 吗 (带 secret) │ └ 否/-3 → secret 不一致 (2.1/2.2) ├─ ffprobe rtsp://127.0.0.1:8554/cam1 有 h264 轨吗 │ └ 否 → FFmpeg/MediaMTX 问题 (第三节) ├─ getMediaList 里有 live/dev_1 且 readerCount0 吗 │ └ 否 → 源未连上 (2.4)看 ZLM 日志 └─ 浏览器 F12 看 *.flv 请求状态 ├ 200 无画面 → 源问题(2.4/4.1) ├ CORS 报错 → 开 allow_cross_domains (2.5) └ mixed-content → https/http 冲突 (4.3)七、配置核对清单每次模拟前过一遍config.ini [api].secret与application.yml zlm.secret完全一致改后重启 ZLMconfig.ini [http].port与application.yml zlm.http-port一致本地用8080避 IISconfig.ini [http] allow_cross_domains1跨域时必须start_sim.bat里MEDIAMTX_EXE / ZLM_DIR / FFMPEG_EXE / TEST_VIDEO / RTSP_URL路径正确启动顺序mediamtx → 等 3s → ZLMediaKit → 等 3s → ffmpeg 推流设备视频地址填rtsp://127.0.0.1:8554/cam1与 FFmpeg 推流 URL 一致防火墙放行 8080或 80/ 554 / 1935验证getServerConfig返回 JSON →ffprobe cam1有 h264 → 前端预览出循环画面