简介本资源为Windows平台下ZLMediaKit流媒体服务器的最新编译可执行版本面向音视频开发工程师、流媒体系统部署人员及嵌入式/安防领域需对接RTSP摄像头的实践者解决Windows环境快速部署、HTTP-FLV低延迟网页直播及按需拉流等核心需求。压缩包共128个文件含23个可执行程序如MediaServer.exe主服务、test_flv.exe等测试工具、15个前端JS与HTML页面、9个CSS/Map调试文件、9个LIB/EXP/PDB/ILK等构建辅助文件以及证书、配置、图标等配套资源整体体积316.99MB开箱即用无需额外编译。已有898人学习下载适用于博客中所述的RTSP转HTTP-FLV网页播放场景尤其适配新增的.live.flv后缀直播流支持资源结构清晰含Swagger API文档支持、Web管理界面与完整测试套件便于快速验证服务状态、调试拉流逻辑及集成至自有业务系统。 最近群里好几个朋友都在问 Windows 上怎么编译 ZLMediaKit 的最新版本正好我前两天刚把 master 分支从头到尾在 Windows 11 Visual Studio 2022 环境里跑通了一遍借着这篇把完整过程写下来。ZLMediaKit 是开源社区里很活跃的流媒体服务器一套代码同时支持 RTSP、RTMP、HLS、HTTP-FLV、WebSocket-FLV、GB28181 这些协议做视频监控接入、直播转推流、录像回放都绕不开它。这篇内容适合两类人一类是想在 Windows 上拿到最新版可执行文件的同学另一类是打算改源码、加协议、做二次开发的工程师文章从环境准备一直写到产物验证中间穿插了不少我实际踩过的坑照着走基本能一次跑通。1. 为什么非要在 Windows 上自己编译一份 ZLMediaKit1.1 Docker 部署和官方 Release 都方便但源码编译的需求依然存在很多人第一反应是ZLMediaKit 不是有 Docker 镜像吗直接用 Docker Desktop 拉一个不就行了确实如果只是临时验证功能、做环境隔离Docker 是最快的路子。但实际用下来有几个问题Docker Desktop 的端口映射和文件挂载在 Windows 下偶尔会有延迟问题流媒体服务对网络性能敏感Docker 的 NAT 模式在高并发拉流场景下会引入额外开销更重要的是Docker 镜像里跑的是 Linux 版本你没法用 Visual Studio 直接调试核心代码。官方 Release 页面偶尔也会放 Windows 预编译包但版本更新往往滞后于 master而且不一定覆盖你需要的选项组合。比如你想开 WebRTC、想内嵌 FFmpeg 做转封装预编译包不一定满足。最可控的方式就是自己从源码编译这也是很多做流媒体接入的团队在 Windows 开发机上采用的主流做法。1.2 源码编译带来的实际收益自己编译最直接的好处是能拿到最新代码里的协议修复和新特性。ZLMediaKit 的迭代速度不慢master 分支经常有 WebRTC 传输优化、GB28181 信令细节调整、HLS 切片逻辑改进这类更新用预编译包或 Docker 镜像总是慢半拍。第二个好处是裁剪和定制。编译时可以通过 CMake 开关关掉不需要的功能模块比如只做 GB28181 接入的业务可以把 WebRTC 相关代码裁掉编译体积和运行时内存都有直观下降。反过来需要转码或录制 MP4 的场景可以在编译期指定依赖的 FFmpeg 路径把能力内嵌进二进制。自己做二次开发就更不用说了改完代码需要立刻编译验证总不能每次都在 Linux 容器里来回折腾。第三个好处是调试体验。用 Visual Studio 打开 CMake 生成的工程文件后可以直接在流媒体收包、解复用、推流这些关键函数上打断点配合即时窗口看内存结构排查问题的效率比对着日志猜高得多。这一点在做私有协议接入时价值极大。2. 编译前的环境准备工具链选型直接影响后续所有环节2.1 Windows 编译 ZLMediaKit 需要准备的东西在 Windows 上编译 ZLMediaKit 需要的工具比 Linux 要少但每一样都有版本讲究。我实测的配置如下可以作为参考工具推荐版本说明操作系统Windows 10/11 x64老版本 Win7 不建议MSVC 最新工具集和 SDK 支持有问题Visual Studio2022 社区版安装时勾选使用 C 的桌面开发工作负载Windows SDK10.0.22621 或更高VS 安装器默认会带务必确认装上了CMake3.18 以上越低版本越容易在 configure 阶段报错Git2.40拉取仓库和更新子模块用这里有一点值得单独强调ZLMediaKit 的 CMake 脚本对版本有隐性要求CMake 3.16 以下会在 FetchContent 或 target_compile_features 阶段直接失败所以装新版 CMake 是省心选择。Windows 上装上 CMake 之后还要保证它在命令行里可以直接敲出来也就是把 CMake 的 bin 目录加入系统 PATH否则后续用 x64 Native Tools 命令行会找不到命令。2.2 Visual Studio 装完还要检查的两个点Visual Studio 2022 社区版是免费使用的安装时间比较长但这一步做扎实能省下后面大量排查时间。装完以后建议手动确认两件事。第一确认使用 C 的桌面开发工作负载下包含MSVC v143 生成工具和Windows 10/11 SDK。缺了 MSVC 工具链的话CMake 配置阶段会提示找不到编译器很多人卡在这一步不是因为没有装 VS而是装 VS 的时候手滑没勾 C 工作负载。第二确认适用于最新 v143 生成工具的 C ATL里有Windows 流媒体相关组件。这里需要说明一下ZLMediaKit 本身的编译依赖不算复杂但 Windows 平台的调试器、性能工具这些组件对后续开发有帮助。如果只是要编译通过ATL 组件不是必须的可装可不装我建议在磁盘空间允许的情况下都装上省得后面做二次调试时缺东少西。2.3 源码目录与路径规划编译 C 项目最怕路径里有中文、空格和特殊符号。ZLMediaKit 的 CMake 脚本在生成中间文件时会拼很多绝对路径一旦路径里有中文字符MSVC 的 cl.exe 经常报出莫名其妙的 C1083 或 C1021 错误错误信息指向的文件明明存在。我习惯把源码放在D:\projects\ZLMediaKit这种纯英文路径下编译输出目录用D:\projects\zlmediakit-build和源码目录分开。这样既方便管理也避免 CMake 源目录和构建目录混在一起导致缓存混乱。3. 完整编译流程从克隆代码到产出 MediaServer.exe3.1 克隆仓库与初始化子模块ZLMediaKit 的代码托管在 GitHub主仓库本身不大但它依赖 zltoolkit 等子模块所以克隆后必须拉子模块这一步非常关键。推荐直接在命令行执行git clone https://github.com/ZLMediaKit/ZLMediaKit.git cd ZLMediaKit git submodule update --init --recursive如果你已经用 TortoiseGit 之类的图形工具克隆过仓库也一定要在仓库目录里执行一次git submodule update --init --recursive否则第三方库目录是空的CMake 配置阶段会直接失败。3.2 用 x64 Native Tools 命令行配置 CMake这一步的关键是使用 VS 自带的 x64 命令行环境而不是普通的 PowerShell 或 CMD因为它会自动把 MSVC 编译器、链接器和 Windows SDK 的环境变量配好。在开始菜单里搜索x64 Native Tools Command Prompt for VS 2022打开后进入源码目录执行cd D:\projects\ZLMediaKit cmake -G Visual Studio 17 2022 -A x64 -DCMAKE_INSTALL_PREFIXD:\projects\zlmediakit-install -B ..\zlmediakit-build这里我把构建目录放在了源码目录外面的..\zlmediakit-build目的前面说过避免源码和构建产物混在一起。-G Visual Studio 17 2022指定生成 VS2022 工程-A x64指定 64 位架构。如果你的机器内存比较大想加快后续编译可以在配置阶段追加-DCMAKE_BUILD_TYPERelease保证最终 build 出来的是 Release 配置。配置阶段输出信息的末尾会出现一堆开关选项类似ENABLE_WEBRTC、ENABLE_FFMPEG、ENABLE_HLS这样的变量默认值在大多数场景下已经够用。如果你不需要 WebRTC 相关逻辑可以在配置命令里加上-DENABLE_WEBRTC0源码里对应模块就不会参与编译体积和编译时间都会下降。3.3 编译并确认产物位置CMake 配置成功后直接在同一个命令行窗口继续执行cmake --build ..\zlmediakit-build --config Release --parallel 8--parallel 8是指并行编译的线程数按你 CPU 的核心数调整16 核机器开到 12 也没问题。首次编译需要拉取和编译第三方依赖时间在十几分钟到半小时不等取决于网速和机器性能耐心等就行。编译完成后可执行文件在build\bin\Release\MediaServer.exe。如果你没有单独指定过安装目录它就在这个位置如果执行过cmake --install则会出现在你设置的D:\projects\zlmediakit-install\bin\下。我建议直接使用 build 目录里的产物方便后续增量编译。3.4 CMake 常用开关的选型思路CMake 配置阶段有一堆ENABLE_开头的开关我见过不少人在这一步纠结。这里按常见业务场景给一个选型参考开关默认值选型建议ENABLE_WEBRTC0需要 WebRTC 推拉流时打开不用的场景关掉可减少依赖ENABLE_FFMPEG0需要转封装、转码时打开前提是能找到 FFmpeg 库ENABLE_HLS1做直播点播基本都要开建议保持默认ENABLE_MP41需要录制 MP4 时打开默认开ENABLE_SRT0走 SRT 协议传输时打开视业务而定ENABLE_JEMALLOC0大并发场景可打开优化内存分配性能需要注意这些开关的默认值在不同版本里可能调整以你拉下来的源码里 CMakeLists.txt 实际输出为准。我的建议是第一次编译不要乱动全部用默认值跑通之后再按需调整。一上来就改一堆开关编译失败了很难判断是开关问题还是环境问题。4. 编译期最容易翻车的四个错误与我的排查过程4.1 子模块没有初始化配置阶段直接卡死我见过最多的一个错误是在 CMake 配置阶段报错错误信息类似CMake Error at 3rdparty/...: Could not find a package configuration file ...或者是配置能过但编译时爆出一堆fatal error C1083: 无法打开包括文件: zltoolkit/...。这个错误几乎都是因为克隆完代码后忘了执行子模块更新命令。ZLMediaKit 把 zltoolkit、mbedtls 等第三方库放在了 git submodule 里不初始化子模块这些目录就是空的。排查思路很简单先ls或dir看一下3rdparty目录下是否有实际文件如果只是空目录或者只有一个.git文件那就是没拉子模块。进入源码目录执行git submodule update --init --recursive再重新配置即可。4.2 CMake 版本太旧configure 阶段就报语法不支持这个问题在 CMake 3.16 及更早版本上比较明显。ZLMediaKit 的 CMakeLists 里用了一些较新的命令和属性比如FetchContent_Declare的部分参数、target_link_options等旧版 CMake 会直接报出 Unknown CMake command 或 unknown policy。这类报错有一个特点错误信息指向的行号在官方脚本里实际是合法的很容易让人误以为是代码问题。排查方法可以在命令行输入cmake --version确认版本。如果低于 3.18我建议直接到 CMake 官网下载最新版安装包安装时勾选 Add CMake to the system PATH for all users 选项装完重开命令窗口生效。4.3 源码路径带中文或空格编译阶段爆出诡异错误这个问题很折磨人因为报错信息五花八门有时是头文件找不到有时是生成器表达式解析失败有时是链接阶段地址错误。根源就一个Windows 上的 MSVC 工具链对带中文、空格的路径支持不完善中间产物会生成大量含绝对路径的.cmd文件这些路径一旦被 cl.exe 按错误的编码解析就会出幻觉一样的编译错误。我自己就经历过一次项目放在D:\视频流服务\ZLMediaKit路径下编译到三分之一时随机报错重启编译错误位置又会变。后来把整个目录搬到D:\projects\下一次性编译通过再没出过问题。所以在这个项目上路径放英文纯路径是硬性要求。4.4 系统里存在多个 OpenSSL 环境链接阶段报冲突Windows 机器上如果装过 Git、Python 的pip包、或者某些网络软件很可能会在 PATH 里残留不同版本的 OpenSSL DLL。ZLMediaKit 默认尝试查找 OpenSSL但找到的库和你当前编译器环境不匹配时链接器会报LNK2038运行时库不匹配或cannot open file libssl.lib这类错误。这里我有两种处理方案。一种是不用 OpenSSL改用项目内置的 mbedTLS配置时加-DENABLE_MBEDTLS1这样不依赖系统 OpenSSL最省事。另一种是安装 vcpkg 并显式指定把 zltoolkit 依赖的库统一从 vcpkg 拉取这个方案更正规但配置起来要学 vcpkg 的用法。对于大多数只为拿到可执行文件或做二次开发的人来说走 mbedTLS 方案已经足够。5. 运行验证确定你编译出来的 MediaServer.exe 是活的5.1 首次启动与 config.ini 的自动生成编译产物拿到了很多人直接双击运行 MediaServer.exe结果发现窗口一闪而过或者在终端里看到一条错误就退出。这个现象通常不是编译问题而是缺少配置文件。MediaServer 第一次启动时会在当前工作目录下自动生成 config.ini如果当前目录没有写权限或者目录路径有问题程序就会报错退出。正确做法是在命令行进入产物目录运行cd D:\projects\zlmediakit-build\bin\Release .\MediaServer.exe正常情况下终端会打印出版本号、支持的协议和监听的端口类似 START [2025-...] HTTP API 端口: 80 [2025-...] RTSP 端口: 554 [2025-...] RTMP 端口: 1935看到这些信息就说明 core 服务已经起来了。此时当前目录下会自动生成 config.ini里面可以调整端口、鉴权密钥、录制路径等参数。5.2 用 ffmpeg 推流并验证多种拉流方式编译成功只代表代码能跑流媒体服务还要实测一下推拉流是否正常。我用一个 mp4 文件做测试先用 ffmpeg 向本地推一路 RTMP 流ffmpeg -re -i D:\test\demo.mp4 -c copy -f flv rtmp://127.0.0.1:1935/live/test注意推流地址里的live是应用名test是流 ID这两个参数在播放地址里要保持一致。推流后另外打开一个终端分别验证几种常见的拉流方式ffplay rtmp://127.0.0.1:1935/live/test ffplay http://127.0.0.1/live/test/hls.m3u8 ffplay http://127.0.0.1/live/test.flv如果本机能正常播放说明 RTMP 接入、HLS 切片、HTTP-FLV 输出这几条链路都是通的。需要说明的是这里指定-c copy只是复用码流不做转码如果推流端的编码格式和播放器不兼容画面可能黑屏这种情况可以换成-c:v libx264 -c:a aac重新推流试一下。5.3 通过 API 接口确认媒体流状态除了直接拉流验证我建议再通过 HTTP API 看一眼媒体流的完整信息。ZLMediaKit 内置了一套 HTTP API默认地址是http://127.0.0.1/index/api/getMediaList?secret035c73f7-bb6b-4889-a715-d9eb2d1925cc上面这个 secret 是默认配置值如果你在 config.ini 里改过 apiSecret要用修改后的值。返回的 JSON 里能看到流 ID、推流源地址、协议类型、码率、在线观看人数等字段。这一步特别适合排查本地能看、远端拉流失败的问题因为能通过这个接口判断流是否真的注册到了服务里以及拉了哪些会话。5.4 常见运行期问题的快速判断运行阶段我最常遇到的有三类问题。一是防火墙弹窗双击 MediaServer.exe 后 Windows 防火墙会询问是否允许网络访问如果点了取消本机能连、局域网其他机器连接就会超时。排查方法是看服务端终端有没有新的连接日志没有日志就是网络层被拦了。二是端口被占用。比如 80 端口被 IIS 或某些开发工具占用了MediaServer 启动时会报 bind 失败。修改 config.ini 里的 HTTP 端口为 8080 这类高位端口即可。三是缺少 web 管理页面。新版 MediaServer 会把前端页面放在 www 目录下运行时需要保证MediaServer.exe同级目录下有www文件夹缺失时访问http://127.0.0.1/会得到 404。这个 www 目录在源码仓库的根目录下编译时有时不会自动拷贝到产物目录需要手动复制一份到运行目录。6. 版本更新识别与重新编译的小心得6.1 判断你拉到的到底是不是最新版本既然标题叫最新编译版本就绕不开一个实际问题你怎么知道自己拉的是不是最新。ZLMediaKit 的版本节奏是每个功能迭代合并后就会打 tag像v6.0、v7.0这样的正式版发布频率不算高但 master 分支的更新是持续不断的。我建议用 Git 命令确认当前代码状态git log -1 --oneline git describe --tags --alwaysgit describe输出如果是形如v7.0-15-g4a3f2b1的内容说明当前 master 比最新 tag v7.0 领先 15 个提交这基本就是官方仓库里最新的代码了。如果你想用稳定版本可以切到 taggit checkout v7.0 -b release-v7.0。开发环境我一般直接跟随 master因为没有版本回退问题。6.2 增量编译时要注意缓存失效ZLMediaKit 这种体量的项目全量编译虽然不至于等太久但增量编译肯定更快。不过增量编译有几个隐藏的坑。比如换了一条新分支之后直接cmake --build有时会报出链接错误这是因为 CMake 的缓存里还保留着旧分支的选项。这种情况先删掉构建目录重新执行配置流程再编译别图省事在旧缓存上硬编。另外子模块的版本也会影响编译结果。每次git pull之后建议同步执行一次git submodule update --init --recursive把第三方库更新到对应版本否则可能遇到接口签名不匹配的编译错误。这个错误经常表现为编译 MediaServer 时 zltoolkit 里的函数参数对不上实际原因就是子模块版本落后于主模块代码。我个人在编译 ZLMediaKit 时习惯建一个简单的批处理文件把子模块更新、CMake 配置、编译三条命令串在一起每次拉新代码后直接跑一遍省得一条条敲。你如果天天和这个项目打交道也建议这么搞至少能少踩好几次命令漏敲的坑。整个流程跑通之后你就会发现Windows 上编译 ZLMediaKit 的核心其实不在编译本身而在于环境干净、路径纯英文、子模块到位这三个前提把这三点守住后面基本是一马平川。本文还有配套的精品资源点击获取 Windows 下 ZLMediaKit 最新版本源码编译全流程指南
简介本资源为Windows平台下ZLMediaKit流媒体服务器的最新编译可执行版本面向音视频开发工程师、流媒体系统部署人员及嵌入式/安防领域需对接RTSP摄像头的实践者解决Windows环境快速部署、HTTP-FLV低延迟网页直播及按需拉流等核心需求。压缩包共128个文件含23个可执行程序如MediaServer.exe主服务、test_flv.exe等测试工具、15个前端JS与HTML页面、9个CSS/Map调试文件、9个LIB/EXP/PDB/ILK等构建辅助文件以及证书、配置、图标等配套资源整体体积316.99MB开箱即用无需额外编译。已有898人学习下载适用于博客中所述的RTSP转HTTP-FLV网页播放场景尤其适配新增的.live.flv后缀直播流支持资源结构清晰含Swagger API文档支持、Web管理界面与完整测试套件便于快速验证服务状态、调试拉流逻辑及集成至自有业务系统。 最近群里好几个朋友都在问 Windows 上怎么编译 ZLMediaKit 的最新版本正好我前两天刚把 master 分支从头到尾在 Windows 11 Visual Studio 2022 环境里跑通了一遍借着这篇把完整过程写下来。ZLMediaKit 是开源社区里很活跃的流媒体服务器一套代码同时支持 RTSP、RTMP、HLS、HTTP-FLV、WebSocket-FLV、GB28181 这些协议做视频监控接入、直播转推流、录像回放都绕不开它。这篇内容适合两类人一类是想在 Windows 上拿到最新版可执行文件的同学另一类是打算改源码、加协议、做二次开发的工程师文章从环境准备一直写到产物验证中间穿插了不少我实际踩过的坑照着走基本能一次跑通。1. 为什么非要在 Windows 上自己编译一份 ZLMediaKit1.1 Docker 部署和官方 Release 都方便但源码编译的需求依然存在很多人第一反应是ZLMediaKit 不是有 Docker 镜像吗直接用 Docker Desktop 拉一个不就行了确实如果只是临时验证功能、做环境隔离Docker 是最快的路子。但实际用下来有几个问题Docker Desktop 的端口映射和文件挂载在 Windows 下偶尔会有延迟问题流媒体服务对网络性能敏感Docker 的 NAT 模式在高并发拉流场景下会引入额外开销更重要的是Docker 镜像里跑的是 Linux 版本你没法用 Visual Studio 直接调试核心代码。官方 Release 页面偶尔也会放 Windows 预编译包但版本更新往往滞后于 master而且不一定覆盖你需要的选项组合。比如你想开 WebRTC、想内嵌 FFmpeg 做转封装预编译包不一定满足。最可控的方式就是自己从源码编译这也是很多做流媒体接入的团队在 Windows 开发机上采用的主流做法。1.2 源码编译带来的实际收益自己编译最直接的好处是能拿到最新代码里的协议修复和新特性。ZLMediaKit 的迭代速度不慢master 分支经常有 WebRTC 传输优化、GB28181 信令细节调整、HLS 切片逻辑改进这类更新用预编译包或 Docker 镜像总是慢半拍。第二个好处是裁剪和定制。编译时可以通过 CMake 开关关掉不需要的功能模块比如只做 GB28181 接入的业务可以把 WebRTC 相关代码裁掉编译体积和运行时内存都有直观下降。反过来需要转码或录制 MP4 的场景可以在编译期指定依赖的 FFmpeg 路径把能力内嵌进二进制。自己做二次开发就更不用说了改完代码需要立刻编译验证总不能每次都在 Linux 容器里来回折腾。第三个好处是调试体验。用 Visual Studio 打开 CMake 生成的工程文件后可以直接在流媒体收包、解复用、推流这些关键函数上打断点配合即时窗口看内存结构排查问题的效率比对着日志猜高得多。这一点在做私有协议接入时价值极大。2. 编译前的环境准备工具链选型直接影响后续所有环节2.1 Windows 编译 ZLMediaKit 需要准备的东西在 Windows 上编译 ZLMediaKit 需要的工具比 Linux 要少但每一样都有版本讲究。我实测的配置如下可以作为参考工具推荐版本说明操作系统Windows 10/11 x64老版本 Win7 不建议MSVC 最新工具集和 SDK 支持有问题Visual Studio2022 社区版安装时勾选使用 C 的桌面开发工作负载Windows SDK10.0.22621 或更高VS 安装器默认会带务必确认装上了CMake3.18 以上越低版本越容易在 configure 阶段报错Git2.40拉取仓库和更新子模块用这里有一点值得单独强调ZLMediaKit 的 CMake 脚本对版本有隐性要求CMake 3.16 以下会在 FetchContent 或 target_compile_features 阶段直接失败所以装新版 CMake 是省心选择。Windows 上装上 CMake 之后还要保证它在命令行里可以直接敲出来也就是把 CMake 的 bin 目录加入系统 PATH否则后续用 x64 Native Tools 命令行会找不到命令。2.2 Visual Studio 装完还要检查的两个点Visual Studio 2022 社区版是免费使用的安装时间比较长但这一步做扎实能省下后面大量排查时间。装完以后建议手动确认两件事。第一确认使用 C 的桌面开发工作负载下包含MSVC v143 生成工具和Windows 10/11 SDK。缺了 MSVC 工具链的话CMake 配置阶段会提示找不到编译器很多人卡在这一步不是因为没有装 VS而是装 VS 的时候手滑没勾 C 工作负载。第二确认适用于最新 v143 生成工具的 C ATL里有Windows 流媒体相关组件。这里需要说明一下ZLMediaKit 本身的编译依赖不算复杂但 Windows 平台的调试器、性能工具这些组件对后续开发有帮助。如果只是要编译通过ATL 组件不是必须的可装可不装我建议在磁盘空间允许的情况下都装上省得后面做二次调试时缺东少西。2.3 源码目录与路径规划编译 C 项目最怕路径里有中文、空格和特殊符号。ZLMediaKit 的 CMake 脚本在生成中间文件时会拼很多绝对路径一旦路径里有中文字符MSVC 的 cl.exe 经常报出莫名其妙的 C1083 或 C1021 错误错误信息指向的文件明明存在。我习惯把源码放在D:\projects\ZLMediaKit这种纯英文路径下编译输出目录用D:\projects\zlmediakit-build和源码目录分开。这样既方便管理也避免 CMake 源目录和构建目录混在一起导致缓存混乱。3. 完整编译流程从克隆代码到产出 MediaServer.exe3.1 克隆仓库与初始化子模块ZLMediaKit 的代码托管在 GitHub主仓库本身不大但它依赖 zltoolkit 等子模块所以克隆后必须拉子模块这一步非常关键。推荐直接在命令行执行git clone https://github.com/ZLMediaKit/ZLMediaKit.git cd ZLMediaKit git submodule update --init --recursive如果你已经用 TortoiseGit 之类的图形工具克隆过仓库也一定要在仓库目录里执行一次git submodule update --init --recursive否则第三方库目录是空的CMake 配置阶段会直接失败。3.2 用 x64 Native Tools 命令行配置 CMake这一步的关键是使用 VS 自带的 x64 命令行环境而不是普通的 PowerShell 或 CMD因为它会自动把 MSVC 编译器、链接器和 Windows SDK 的环境变量配好。在开始菜单里搜索x64 Native Tools Command Prompt for VS 2022打开后进入源码目录执行cd D:\projects\ZLMediaKit cmake -G Visual Studio 17 2022 -A x64 -DCMAKE_INSTALL_PREFIXD:\projects\zlmediakit-install -B ..\zlmediakit-build这里我把构建目录放在了源码目录外面的..\zlmediakit-build目的前面说过避免源码和构建产物混在一起。-G Visual Studio 17 2022指定生成 VS2022 工程-A x64指定 64 位架构。如果你的机器内存比较大想加快后续编译可以在配置阶段追加-DCMAKE_BUILD_TYPERelease保证最终 build 出来的是 Release 配置。配置阶段输出信息的末尾会出现一堆开关选项类似ENABLE_WEBRTC、ENABLE_FFMPEG、ENABLE_HLS这样的变量默认值在大多数场景下已经够用。如果你不需要 WebRTC 相关逻辑可以在配置命令里加上-DENABLE_WEBRTC0源码里对应模块就不会参与编译体积和编译时间都会下降。3.3 编译并确认产物位置CMake 配置成功后直接在同一个命令行窗口继续执行cmake --build ..\zlmediakit-build --config Release --parallel 8--parallel 8是指并行编译的线程数按你 CPU 的核心数调整16 核机器开到 12 也没问题。首次编译需要拉取和编译第三方依赖时间在十几分钟到半小时不等取决于网速和机器性能耐心等就行。编译完成后可执行文件在build\bin\Release\MediaServer.exe。如果你没有单独指定过安装目录它就在这个位置如果执行过cmake --install则会出现在你设置的D:\projects\zlmediakit-install\bin\下。我建议直接使用 build 目录里的产物方便后续增量编译。3.4 CMake 常用开关的选型思路CMake 配置阶段有一堆ENABLE_开头的开关我见过不少人在这一步纠结。这里按常见业务场景给一个选型参考开关默认值选型建议ENABLE_WEBRTC0需要 WebRTC 推拉流时打开不用的场景关掉可减少依赖ENABLE_FFMPEG0需要转封装、转码时打开前提是能找到 FFmpeg 库ENABLE_HLS1做直播点播基本都要开建议保持默认ENABLE_MP41需要录制 MP4 时打开默认开ENABLE_SRT0走 SRT 协议传输时打开视业务而定ENABLE_JEMALLOC0大并发场景可打开优化内存分配性能需要注意这些开关的默认值在不同版本里可能调整以你拉下来的源码里 CMakeLists.txt 实际输出为准。我的建议是第一次编译不要乱动全部用默认值跑通之后再按需调整。一上来就改一堆开关编译失败了很难判断是开关问题还是环境问题。4. 编译期最容易翻车的四个错误与我的排查过程4.1 子模块没有初始化配置阶段直接卡死我见过最多的一个错误是在 CMake 配置阶段报错错误信息类似CMake Error at 3rdparty/...: Could not find a package configuration file ...或者是配置能过但编译时爆出一堆fatal error C1083: 无法打开包括文件: zltoolkit/...。这个错误几乎都是因为克隆完代码后忘了执行子模块更新命令。ZLMediaKit 把 zltoolkit、mbedtls 等第三方库放在了 git submodule 里不初始化子模块这些目录就是空的。排查思路很简单先ls或dir看一下3rdparty目录下是否有实际文件如果只是空目录或者只有一个.git文件那就是没拉子模块。进入源码目录执行git submodule update --init --recursive再重新配置即可。4.2 CMake 版本太旧configure 阶段就报语法不支持这个问题在 CMake 3.16 及更早版本上比较明显。ZLMediaKit 的 CMakeLists 里用了一些较新的命令和属性比如FetchContent_Declare的部分参数、target_link_options等旧版 CMake 会直接报出 Unknown CMake command 或 unknown policy。这类报错有一个特点错误信息指向的行号在官方脚本里实际是合法的很容易让人误以为是代码问题。排查方法可以在命令行输入cmake --version确认版本。如果低于 3.18我建议直接到 CMake 官网下载最新版安装包安装时勾选 Add CMake to the system PATH for all users 选项装完重开命令窗口生效。4.3 源码路径带中文或空格编译阶段爆出诡异错误这个问题很折磨人因为报错信息五花八门有时是头文件找不到有时是生成器表达式解析失败有时是链接阶段地址错误。根源就一个Windows 上的 MSVC 工具链对带中文、空格的路径支持不完善中间产物会生成大量含绝对路径的.cmd文件这些路径一旦被 cl.exe 按错误的编码解析就会出幻觉一样的编译错误。我自己就经历过一次项目放在D:\视频流服务\ZLMediaKit路径下编译到三分之一时随机报错重启编译错误位置又会变。后来把整个目录搬到D:\projects\下一次性编译通过再没出过问题。所以在这个项目上路径放英文纯路径是硬性要求。4.4 系统里存在多个 OpenSSL 环境链接阶段报冲突Windows 机器上如果装过 Git、Python 的pip包、或者某些网络软件很可能会在 PATH 里残留不同版本的 OpenSSL DLL。ZLMediaKit 默认尝试查找 OpenSSL但找到的库和你当前编译器环境不匹配时链接器会报LNK2038运行时库不匹配或cannot open file libssl.lib这类错误。这里我有两种处理方案。一种是不用 OpenSSL改用项目内置的 mbedTLS配置时加-DENABLE_MBEDTLS1这样不依赖系统 OpenSSL最省事。另一种是安装 vcpkg 并显式指定把 zltoolkit 依赖的库统一从 vcpkg 拉取这个方案更正规但配置起来要学 vcpkg 的用法。对于大多数只为拿到可执行文件或做二次开发的人来说走 mbedTLS 方案已经足够。5. 运行验证确定你编译出来的 MediaServer.exe 是活的5.1 首次启动与 config.ini 的自动生成编译产物拿到了很多人直接双击运行 MediaServer.exe结果发现窗口一闪而过或者在终端里看到一条错误就退出。这个现象通常不是编译问题而是缺少配置文件。MediaServer 第一次启动时会在当前工作目录下自动生成 config.ini如果当前目录没有写权限或者目录路径有问题程序就会报错退出。正确做法是在命令行进入产物目录运行cd D:\projects\zlmediakit-build\bin\Release .\MediaServer.exe正常情况下终端会打印出版本号、支持的协议和监听的端口类似 START [2025-...] HTTP API 端口: 80 [2025-...] RTSP 端口: 554 [2025-...] RTMP 端口: 1935看到这些信息就说明 core 服务已经起来了。此时当前目录下会自动生成 config.ini里面可以调整端口、鉴权密钥、录制路径等参数。5.2 用 ffmpeg 推流并验证多种拉流方式编译成功只代表代码能跑流媒体服务还要实测一下推拉流是否正常。我用一个 mp4 文件做测试先用 ffmpeg 向本地推一路 RTMP 流ffmpeg -re -i D:\test\demo.mp4 -c copy -f flv rtmp://127.0.0.1:1935/live/test注意推流地址里的live是应用名test是流 ID这两个参数在播放地址里要保持一致。推流后另外打开一个终端分别验证几种常见的拉流方式ffplay rtmp://127.0.0.1:1935/live/test ffplay http://127.0.0.1/live/test/hls.m3u8 ffplay http://127.0.0.1/live/test.flv如果本机能正常播放说明 RTMP 接入、HLS 切片、HTTP-FLV 输出这几条链路都是通的。需要说明的是这里指定-c copy只是复用码流不做转码如果推流端的编码格式和播放器不兼容画面可能黑屏这种情况可以换成-c:v libx264 -c:a aac重新推流试一下。5.3 通过 API 接口确认媒体流状态除了直接拉流验证我建议再通过 HTTP API 看一眼媒体流的完整信息。ZLMediaKit 内置了一套 HTTP API默认地址是http://127.0.0.1/index/api/getMediaList?secret035c73f7-bb6b-4889-a715-d9eb2d1925cc上面这个 secret 是默认配置值如果你在 config.ini 里改过 apiSecret要用修改后的值。返回的 JSON 里能看到流 ID、推流源地址、协议类型、码率、在线观看人数等字段。这一步特别适合排查本地能看、远端拉流失败的问题因为能通过这个接口判断流是否真的注册到了服务里以及拉了哪些会话。5.4 常见运行期问题的快速判断运行阶段我最常遇到的有三类问题。一是防火墙弹窗双击 MediaServer.exe 后 Windows 防火墙会询问是否允许网络访问如果点了取消本机能连、局域网其他机器连接就会超时。排查方法是看服务端终端有没有新的连接日志没有日志就是网络层被拦了。二是端口被占用。比如 80 端口被 IIS 或某些开发工具占用了MediaServer 启动时会报 bind 失败。修改 config.ini 里的 HTTP 端口为 8080 这类高位端口即可。三是缺少 web 管理页面。新版 MediaServer 会把前端页面放在 www 目录下运行时需要保证MediaServer.exe同级目录下有www文件夹缺失时访问http://127.0.0.1/会得到 404。这个 www 目录在源码仓库的根目录下编译时有时不会自动拷贝到产物目录需要手动复制一份到运行目录。6. 版本更新识别与重新编译的小心得6.1 判断你拉到的到底是不是最新版本既然标题叫最新编译版本就绕不开一个实际问题你怎么知道自己拉的是不是最新。ZLMediaKit 的版本节奏是每个功能迭代合并后就会打 tag像v6.0、v7.0这样的正式版发布频率不算高但 master 分支的更新是持续不断的。我建议用 Git 命令确认当前代码状态git log -1 --oneline git describe --tags --alwaysgit describe输出如果是形如v7.0-15-g4a3f2b1的内容说明当前 master 比最新 tag v7.0 领先 15 个提交这基本就是官方仓库里最新的代码了。如果你想用稳定版本可以切到 taggit checkout v7.0 -b release-v7.0。开发环境我一般直接跟随 master因为没有版本回退问题。6.2 增量编译时要注意缓存失效ZLMediaKit 这种体量的项目全量编译虽然不至于等太久但增量编译肯定更快。不过增量编译有几个隐藏的坑。比如换了一条新分支之后直接cmake --build有时会报出链接错误这是因为 CMake 的缓存里还保留着旧分支的选项。这种情况先删掉构建目录重新执行配置流程再编译别图省事在旧缓存上硬编。另外子模块的版本也会影响编译结果。每次git pull之后建议同步执行一次git submodule update --init --recursive把第三方库更新到对应版本否则可能遇到接口签名不匹配的编译错误。这个错误经常表现为编译 MediaServer 时 zltoolkit 里的函数参数对不上实际原因就是子模块版本落后于主模块代码。我个人在编译 ZLMediaKit 时习惯建一个简单的批处理文件把子模块更新、CMake 配置、编译三条命令串在一起每次拉新代码后直接跑一遍省得一条条敲。你如果天天和这个项目打交道也建议这么搞至少能少踩好几次命令漏敲的坑。整个流程跑通之后你就会发现Windows 上编译 ZLMediaKit 的核心其实不在编译本身而在于环境干净、路径纯英文、子模块到位这三个前提把这三点守住后面基本是一马平川。本文还有配套的精品资源点击获取