作海康威视SDK二次开发的最烦的往往不是写业务代码而是最后收尾那一下——把程序打包成安装包。开发机上跑得好好的换到客户电脑上就各种缺DLL、连不上设备、配置文件找不到。我自己前后折腾过不少次从最早的WinForm项目到后来整体切到WPF客户端中间踩过的坑足够写一篇长文了。这篇文章就是把我在WPF/WinForm客户端对接海康威视SDK时制作安装包的完整思路和实操过程整理出来给正准备收尾上线的朋友做个参考。1. 打包之前先把项目结构理清楚很多人一上来就找打包工具其实在动手之前最该做的是把“要打进安装包的东西”分门别类列清楚。海康威视客户端和普通业务软件不太一样它除了你自己的exe和DLL还牵扯到海康的SDK运行库、视频组件、配置文件弄混一个就要出问题。1.1 明确程序集和SDK依赖的边界先看一张粗粒度清单你项目里多半有这些文件你自己的主程序exe以及随项目生成的所有业务DLL第三方控件的运行库比如图表、UI框架之类的数据库相关文件包括数据库引擎、配置文件海康威视的SDK运行库包含HCNetSDK.dll、PlayCtrl.dll等播放库以及它们附带的一些底层DLL配置文件比如App.config、连接字符串、设备参数配置运行环境一般指.NET Framework对应版本或者.NET 8运行时我实际在做项目的时候会单独建一个“部署清单”的Excel表格每一类文件都注明来源目录、目标安装目录、是否可选组件。别嫌麻烦后期排查问题全靠它。1.2 32位和64位架构必须提前定死海康SDK的DLL分x86和x64两种这个事在打包时是第一个要确认的。很多同事在这上面吃过亏程序编译的是AnyCPU到客户机器上运行到SDK初始化就报错查半天发现是DLL架构不匹配。我个人的建议是尽量统一编译目标。如果客户环境是老旧的Windows 7 32位系统那整个程序编译成x86SDK也放x86版本如果客户环境是64位系统并且有内存占用较大的需求那就编译为x64SDK放x64版本尽量避免AnyCPU海康SDK加载时会找当前进程架构对应的DLLAnyCPU在这种场景下反而容易出问题还有一点海康的SDK里有个HCNetSDK.dll它的加载依赖一些Visual C运行库。打包的时候别漏掉不然客户电脑上会报“找不到MSVCR100.dll”之类的错误。1.3 配置文件的位置和内容先规划再打包对于WPF程序通常会有App.config文件编译之后变成“程序名.exe.config”。WinForm也是类似。配置文件的处理重点在于哪些配置项是机器相关的哪些是全局固定的。机器相关的配置项比如数据库连接字符串、设备IP端口、录像存储路径这些不应该在打包时写死而应该在安装过程中或者程序首次运行时生成。我习惯的做法是打包时只带一份默认配置文件安装完成后程序首次启动时检查配置完整性缺了就让用户填或者从安装目录下的“配置模板”目录读取。这样有个明显的好处换一台电脑安装包不用重新做客户改配置文件或者通过界面设置就能适配新环境。2. 安装工具怎么选我为什么最后固定用Inno Setup打包工具圈子里常用的无非就是那几样Visual Studio自带的InstallShield、Advanced Installer、Inno Setup、NSIS还有早期的Wix。我不打算一个个全讲只说大家最常用的对比以及为什么我最后在项目里固定下了Inno Setup。2.1 几种主流安装工具的真实使用感受工具优点缺点适合场景InstallShield集成在VS里上手门槛低脚本逻辑受限体积大简单项目、一次性打包Advanced Installer图形化操作好支持多语言界面高级功能收费许可证费用不低需要漂亮安装界面的商业软件Inno Setup免费、脚本可控、安装包体积小初始学习曲线偏陡项目经常更新、需要批量打包NSIS脚本插件生态强性能高需要自己写大量脚本有定制化安装需求的极客型项目我一开始图省事用的InstallShield但项目进入稳定迭代期后每两周就要发一次版本InstallShield那个图形化配置反复改起来特别费劲后来干脆把整个打包脚本用Inno Setup重新写了一遍。现在项目里不管WPF还是WinForm客户端全部用Inno Setup出包一条命令行就能打出新版本安装包效率翻了好几倍。2.2 为什么海康项目推荐Inno Setup海康二次开发项目有个特点依赖文件多而且SDK的DLL可能随着版本更新而变化。Inno Setup的脚本式管理正好契合这个场景——文件列表、注册表项、快捷方式、卸载逻辑全部用文本维护改起来就是直接编辑脚本不用在图形界面里点来点去。另外一个关键点是Inno Setup对运行库检测和可选组件的控制非常灵活。比如我可以在脚本里判断系统是否装了对应版本的.NET Framework没装就自动帮你引入离线安装包装完主程序再继续。这个流程在InstallShield里也能做但没有Inno Setup脚本这么直白。3. 正式打包前需要准备好的资源和环境写Inno Setup脚本之前有几样东西得提前准备好不然写脚本的过程中会被卡住。3.1 收集海康SDK的完整文件清单海康威视的SDK压缩包解压后一般能看到几个子目录库文件目录包含HCNetSDK.dll、GdiPlus相关、音频库等PlayCtrl播放器库用于预览和回放依赖库目录比如HCCore相关的DLL示例代码和头文件这个不需要打包打包时只需要把运行所需的DLL拷贝进安装包。具体需要哪些有个笨办法先把DLL全部放进去装到干净的虚拟机里跑一遍如果发现某个DLL根本没被用到再从清单里移除。如果被裁剪了就用Dependency Walker或者Process Explorer看加载链缺哪个补哪个。我实际测试下来海康SDK里有一部分是软依赖就是只在特定功能下才调用比如语音对讲这部分DLL建议不管用不用都保留反正体积不大省得出稀奇古怪的问题。3.2 准备.NET运行时和VC运行库现在有些客户机器是干净的什么运行库都没有。安装包里最好把以下内容作为前置安装组件.NET Framework 4.8如果程序目标框架是.NET Framework.NET 8 Desktop Runtime如果程序目标是.NET 8Visual C 2015-2022 Redistributablex86和x64都带上如果是64位程序VC运行库的x64版本必须装有一种更稳妥的做法在打包时把运行库的离线安装包放到安装包的某个子目录然后在Inno Setup脚本里写安装顺序先装运行库再装主程序。注意顺序装错比如主程序装完才装运行库某些系统上会要求重启后才生效体验很差。3.3 程序本身做一次“绿色发布”验证正式做安装包之前我每次都先把编译输出的整个目录拷贝到另一台干净机器上直接运行exe看看能不能跑起来。这个过程叫“绿色验证”。如果这都跑不起来那问题大概率不在打包上而在程序本身的依赖配置上先回去改代码比改打包脚本更快。绿色验证时重点看程序目录是不是全部文件都在有没有漏拷贝的DLL配置文件的相对路径是否能被正确读取数据库能不能连上如果本地要装数据库引擎的话海康SDK是否能正常初始化设备列表这些在开发机器上都通过之后我才会开始写打包脚本。4. Inno Setup脚本的完整拆解与写法我直接用一段实际项目的关键脚本来做说明。这个项目是WPF客户端目标框架是.NET Framework 4.8海康SDK用的是x64版本。4.1 Inno Setup脚本的基本框架; 脚本使用Inno Setup 6.x编写 [Setup] AppName海康视频监控客户端 AppVersion1.2.0 AppPublisher内部项目组 AppPublisherURLhttp://内部地址 DefaultDirName{pf}\HikClient DefaultGroupName海康视频监控客户端 OutputDir.\InstallPack OutputBaseFilenameHikClient_Setup_1.2.0_x64 Compressionlzma2/max SolidCompressionyes ArchitecturesAllowedx64compatible ArchitecturesInstallIn64BitModex64compatible PrivilegesRequiredadmin ; 这个选项很关键决定是否生成64位安装包 [Languages] Name: chinesesimp; MessagesFile: compiler:Default.isl [Run] ; 先装VC运行库再装.NET Framework Filename: {tmp}\vcredist_x64.exe; Parameters: /install /quiet /norestart; Check: NotVCInstalled; Flags: waituntilterminated Filename: {tmp}\NDP48-x86-x64-AllOS-ENU.exe; Parameters: /quiet /norestart; Check: NotDotNetInstalled; Flags: waituntilterminated [Files] Source: ..\bin\x64\*; DestDir: {app}; Flags: recursesubdirs createallsubdirs ; 把运行库离线包拷到临时目录 Source: ..\redist\vcredist_x64.exe; DestDir: {tmp}; Flags: deleteafterinstall Source: ..\redist\NDP48-x86-x64-AllOS-ENU.exe; DestDir: {tmp}; Flags: deleteafterinstall [Icons] Name: {group}\海康视频监控客户端; Filename: {app}\HikClient.exe Name: {commondesktop}\海康视频监控客户端; Filename: {app}\HikClient.exe这段脚本里有几个细节我提醒一下ArchitecturesInstallIn64BitModex64compatible是Inno Setup 6.3以后的写法表示安装包本身可以在64位系统上执行并且安装到64位目录。老版本直接写ArchitecturesInstallIn64BitModex64[Files]段用recursesubdirs把整个bin目录递归打进包比你手动列几百个DLL靠谱得多{tmp}目录下的运行库安装完就删除避免给客户电脑留垃圾文件4.2 判断系统缺不缺运行库上面脚本里我写了两个检查函数这里具体展开。[Code] function NotVCInstalled(): Boolean; begin // 检查注册表里是否已经存在VC运行库条目 Result : not RegKeyExists(HKLM, SOFTWARE\Microsoft\VisualStudio\14.0\VC\Runtimes\x64); end; function NotDotNetInstalled(): Boolean; var version: Cardinal; begin // 检查.NET Framework 4.8的版本号528040表示安装了4.8 Result : True; if RegQueryDWordValue(HKLM, SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full, Release, version) then begin if version 528040 then Result : False; end; end;这套做法的核心思路是安装前先检查缺了才安装不缺就跳过。有些安装包不管三七二十一强制装运行库遇到已经装了更高版本的系统往往需要重启客户体验很差。用检查函数做前置判断能省掉大量不必要的麻烦。4.3 安装完成后的卸载逻辑和日志安装包还有一块常被忽视的地方是卸载。海康客户端通常会有日志文件、临时文件、设备注册信息卸载时不清理干净重装的时候容易出问题。我在脚本里加了卸载时删除日志和配置的步骤[UninstallDelete] Type: filesandordirs; Name: {app}\Logs Type: filesandordirs; Name: {app}\DeviceCache Type: files; Name: {userappdata}\HikClient\config.ini清理日志这个操作要慎重如果客户有保存录像和配置文件在程序目录之外的需求不要一股脑全删。最好是拆成两部分程序目录下的缓存和运行日志可删客户主动保存的数据比如录像导出目录不动。5. 把海康SDK的坑提前填平讲完通用打包流程这一节专门说海康SDK和安装包之间的那些“微妙关系”。这些内容你在官方SDK文档里基本看不到全是实际部署中被坑过才总结出来的。5.1 SDK初始化失败的头号原因DLL搜索路径WPF程序的默认DLL搜索路径是程序所在目录、系统目录、系统PATH。海康的HCNetSDK.dll在加载PlayCtrl.dll、HCCore等库的时候也是先从自己的模块路径下找。正常情况下只要所有SDK DLL都放在程序目录下是不需要额外设置搜索路径的。但有一种特殊情况如果你把SDK DLL放在子目录比如{app}\SDK下然后调用HCNetSDK初始化就会出现明明DLL都在却加载不了的情况。解决办法有两个方向简单粗暴所有DLL平铺在程序根目录包括SDK的结构清晰SDK放在子目录同时在程序启动时调用SetDllDirectory或AddDllDirectory指定搜索路径我自己的项目为了管理方便选择了后一种。在程序入口处加上一行[System.Runtime.InteropServices.DllImport(kernel32.dll, SetLastError true, CharSet System.Runtime.InteropServices.CharSet.Unicode)] private static extern bool SetDllDirectory(string lpPathName); // 在Main函数最开始调用 SetDllDirectory(Path.Combine(AppDomain.CurrentDomain.BaseDirectory, SDK));这里有个顺序问题先设定目录再去调用海康SDK的初始化接口。如果是WPF项目建议在Application启动事件里处理或者在Main方法的早期。别等到窗体加载完才搞太晚了。5.2 多个DLL版本冲突怎么处理海康SDK在某个版本之后依赖的第三方DLL比如音频相关的越来越多而且有些DLL和第三方控件引用的版本不一致。最容易出现的是“ollvm.dll版本冲突”实际项目中遇到过不止一次。处理方法说穿了很简单把SDK运行库单独放到子目录与主程序自己的DLL隔离主程序和SDK各自用自己目录下的全部依赖不共享如果两个DLL名字一样但版本不同不要强行合并只能用目录隔离这种方法唯一的代价是稍微占用一点磁盘空间但能换来很大的稳定性。打包时在[Files]段里单独加一行把SDK目录拷到{app}\SDK下和主程序分离即可。5.3 海康SDK的初始化参数文件海康的SDK初始化时有些功能比如设备能力集、部分接口依赖一个参数文件或者日志目录。官方SDK有接口可以指定日志保存路径这个路径在部署时必须保证存在且有写权限。我之前遇到过一个情况程序安装在Program Files目录下SDK初始化后需要写日志而客户是标准用户权限没有对Program Files的写入权限日志就写不进去导致SDK某些功能不可用。最典型的是设备搜索功能偶尔没反应查了半天发现是日志路径权限问题。现在我的做法是把SDK的日志目录设置在{localappdata}\HikClientLog在安装脚本里预先创建好这个目录如果目录创建失败程序启动时也会自动尝试创建并给出对应提示配置文件的路径同理原则上不写入Program Files下的程序目录而写入{userappdata}或者{commonappdata}。这样能兼容各种权限模式基本不会再出现客户环境跑不动的情况。6. WinForm和WPF在打包上的区别做海康客户端的时候老项目基本是WinForm新项目大多切到WPF。两种框架在打包时的关注点其实有区别这里单独拿出来说。6.1 WinForm打包相对简单的点WinForm项目整体上依赖比较直接程序集少运行时对系统资源的感知也简单。打包时注意数据库连接如果用的是本地SQLite注意把SQLite的混合模式DLL放对位置如果用了第三方UI控件比如皮肤控件一定要确认对应版本有些皮肤DLL和主程序版本不匹配会导致直接崩溃WinForm的配置文件相对简易连接字符串、设备参数基本都在App.config里打不打包问题不大WinForm打包时最容易出错的是自动升级功能。很多老项目有自己的升级器升级器在安装包里必须放在主程序的同级目录不能放到别的子目录否则升级逻辑找不到路径就罢工。6.2 WPF打包要注意的细节WPF项目打包时要留意的地方明显更多WPF程序可能有资源文件图片、字体、样式字典这些是嵌入资源不打进安装包没关系但如果是Content类型的外部资源漏打就会白屏或图标丢失WPF程序依赖.NET Framework或.NET RunTime目标框架一定要写清楚安装包里的前置组件要匹配WPF的高DPI支持在客户机器上有时会出现字体模糊或布局错位调试时多换几台分辨率不同的电脑测如果用到Prism或者MVVM框架程序集数量比WinForm多不少建议用recursesubdirs方式整体打包不要只挑“需要的”文件还有一个细节WPF程序有时会引用一些原生DLL比如用OpenCV做图像处理这些原生DLL不会自动复制到输出目录。打包前要检查是否有独立存在的原生DLL把它手动放进文件清单。6.3 界面权限管理员权限和UAC海康客户端的很多操作涉及系统级资源比如修改本地网络配置、加载驱动、写入系统注册表。这类程序装完最好让程序自身具备管理员权限。策略有两种程序manifest里声明管理员权限每次运行都弹UAC安装时给程序目录设置权限程序以普通用户运行只有特定操作提权内部工具类项目我一般选择第一种省事。面向客户的软件选择第二种体验更好。WPF和WinForm在manifest设置上没有本质区别关键要记得设置并验证。7. 打包前后必须跑通的验证清单脚本写完了安装包生成了不代表交付完成。我每个月发版本前都要过一遍验证清单这里分享给大家。7.1 干净虚拟机上跑一遍安装在开发环境上跑成功不是真成功一定要在以下环境类型的干净机器上测试Windows 10 64位无任何运行库Windows 11 64位有旧版本.NET环境带有标准杀毒软件的企业办公环境虚拟机建议安装Windows评估版或合规授权版本安装完之后不做任何额外配置直接跑安装包看能否顺利完成。7.2 验证安装包内文件完整性和版本号Inno Setup打完包可以生成一个带校验码的文件清单在安装结束后用脚本检测主程序版本号和关键DLL是否存在。这一步能有效防止“装完后打不开但不知道少了什么”的尴尬情况。7.3 卸载后残留文件检查卸载后检查下面这些位置程序目录是否全部删除公共数据目录是否还剩了配置文件开始菜单和桌面快捷方式是否清除干净注册表里是否有残留的App项这一轮检查过这个安装包才算达到发布标准。8. 常见问题与排查实录这里列几个我在实际打包过程中遇到的典型问题基本是客户现场反馈回来然后我一步步定位出来的。8.1 客户机器上双击主程序没反应最常见的情况程序安装完成快捷方式也有双击鼠标后什么反应也没有任务管理器里也没有进程。排查顺序先看事件查看器.NET Runtime错误里有没有异常信息缺依赖库是第一怀疑对象用Dependency Walker或者直接看事件日志里报错的是哪个模块如果日志里看到“Cannot load ... native library”基本就是VC运行库没装或者版本不匹配如果是x86/x64不匹配会看到“BadImageFormatException”处理的办法检查安装脚本里运行库安装是否执行成功同时检查程序编译目标架构和SDK架构是否匹配。8.2 SDK初始化返回错误码但开发机一切正常开发机正常客户机器报错这个就很典型了。海康SDK的初始化失败码如果指向“加载动态库失败”基本可以锁定SDK DLL没有随安装包拷贝到程序目录被安全软件拦截导致加载失败SDK所需VC运行库缺失我的处理技巧在程序里把SDK的日志功能提前打开日志会直接告诉你少了哪个DLL或者哪个依赖组件没就绪。别靠猜看日志定位是最快的。8.3 数据库连接不上的问题客户端需要连本地数据库时安装完成后经常遇到连接失败。排查重点系统服务是否启动比如SQLServer的服务是否正常运行配置文件中的连接串是否指向了当前机器的正确实例名数据库文件是否被安装包正确放置到指定路径我通常在安装脚本中用[Run]段注册Windows服务并用[Registry]段写入数据库路径这样整个系统才真正“装好了”。8.4 杀毒软件误报Inno Setup生成的安装包有个特点如果不做代码签名很多杀毒软件会直接拦截。海康SDK包含一些底层驱动文件更容易触发误报。解决办法是给安装包加数字签名。内部项目如果预算有限可以用自签名证书对外发布的项目还是建议买正规的代码签名证书。签名后的安装包在SmartScreen提示和杀毒软件拦截率上会有明显改善。9. 关于脚本维护和持续集成的一句话建议最后说一个容易被忽略的点安装包脚本和代码一样需要版本管理。我推荐把Inno Setup脚本文件.iss、运行库路径说明、部署清单全部放进代码仓库里和主程序同一次提交。这样每次发版CI构建出程序集紧接着用命令行编译安装包ISCC.exe HikClient_Setup.issISCC是Inno Setup自带的命令行编译器把它和Inno Setup安装目录关联后打包全过程不需要人工操作。我最近一次发版本整个流程从代码提交到生成安装包总共不到十分钟。如果你现在的项目还在靠人工在安装工具里面点鼠标选文件强烈建议切换成脚本方式哪怕只是把这个过程自动化节省的时间都很可观。海康客户端这类项目打包说到底是“依赖版本管理”的延伸。只要把依赖清单、安装脚本、运行库和SDK的状态都管理到位发版也不过是一条命令的事。我自己在打包上踩过的坑全部集中在“没提前检查”、“架构不一致”、“权限没考虑”这三件事上。把这几个点提前堵住后面基本就顺畅了。
