简介这是一份基于Electron构建的UDP调试工具源码包面向需要在桌面端快速创建多个UDP客户端和服务器的JavaScript开发者。工具支持任意主机与端口添加实例内置随机数据生成器可按固定时间间隔自动发送数据报非常适合用于验证或测试自研UDP服务。包体共30个文件以12个JS脚本为核心配合5个CSS样式文件、3个JSON配置和少量图片资源总大小约301KB结构简洁便于直接阅读与二次开发。资源已有1298人学习代码中清晰划分了客户端管理、服务器管理、数据生成等模块并附带Electron打包配置可帮助你从开发到生成exe快速落地是学习Electron进程通信与UDP网络编程的实用参考。1. 为什么放着现成的网络调试助手不用偏要自己写一个 UDP 收发工具如果你做过设备联调或者协议对接大概率有过这样的崩溃瞬间被测设备只支持 UDP文档里写着“向 192.168.1.64:9000 发送报文”结果你打开命令行用nc -u 192.168.1.64 9000发包终端里却只能显示 UTF-8 文本设备回给你一段十六进制数据时屏幕上全是乱码。再比如说你要验证本机某个端口有没有 UDP 服务在监听Windows 下用netstat -ano只能看到端口状态看不到内容最后还是得开 Wireshark 抓包然后在几十条背景广播里找那一条关键报文。这种体验真的只适合偶尔用一次的人天天搞 UDP 联调的话效率实在太低了。所以我花了一个晚上用 Electron 写了一个极简的 UDP 客户端和服务器二合一工具也就是其实验项目中的核心结构。目标非常明确本机任意端口上能开一个 UDP 服务器实时把收到的数据报显示在界面上同时能向任意目标主机和端口发送文本或十六进制数据报收发记录统一展示方便我观察请求和响应的对应关系。不追求复杂功能能覆盖日常调试需求的 80% 就够了。可能有人会问既然 VS Code 都是 Electron 写的拿它来做这种轻量工具是不是太“重”了其实恰恰相反。Electron 非常适合这类工具型应用原因有三个。第一跨平台一致性好Windows、Linux、macOS 打包后都能跑不像某些老牌网络调试助手只维护 Windows 版。第二Node.js 原生自带 dgram 模块UDP 的服务器和客户端加起来不到一百行代码不需要引入任何第三方网络库。第三Electron 的主进程和渲染进程分离机制天然适合“网络收发的逻辑放主进程界面展示放渲染进程”这种架构练习价值很高。对于刚接触 Electron 的人来说与其做那些纯展示型的 Demo不如从 UDP 收发工具入手因为它是真的能用到工作上。2. UDP 和 TCP 的本质差别以及 Node dgram 模块的工作边界写这个工具之前我觉得有必要把 UDP 的几个关键概念重新捋一遍因为很多人在设计界面的时候会把 TCP 的那套理念生搬硬套过来结果做出一个“看起来能用、用起来别扭”的工具。2.1 “数据报”到底意味着什么标题里刻意用了“数据报”而不是“数据包”这个词不是装腔作势它准确描述了 UDP 的行为。TCP 是流协议你调用 write 发送 1024 字节对端读的时候可能拆成两次返回也可能合并到一次里面边界完全由内核决定。UDP 则严格保留边界你 send 出去的一个 Buffer对端 message 事件里拿到的就是一个完整的、边界一致的数据报。所以在界面设计上我采用“一行一个数据报”的展示方式每一行对应一次接收或发送而不用像 TCP 调试工具那样去做粘包拆包处理。另一个重要的区别是连接状态。TCP 建立连接之前有三次握手之后维持连接状态断开时有四次挥手。UDP 没有这些发送方只需要知道目标 IP 和端口就能把报文丢出去接收方被动地接收。这也带来一个实际影响UDP 工具里“服务器”和“客户端”的界限并不像 TCP 那么清晰。TCP 里服务端必须 listen accept客户端必须 connectUDP 里服务器只是 bind 到了本地端口而客户端如果想接收响应的报文也必须拥有一个本地端口来接收。我做的工具干脆把模式做成两个独立面板一个负责“监听”一个负责“发送”组合使用就能覆盖绝大多数场景。2.2 dgram 模块的核心 API 路径Node.js 的 dgram 模块已经封装好了 UDP 的全部操作核心逻辑并不复杂dgram.createSocket(type)创建 sockettype 传udp4或udp6socket.bind(port, address)绑定本地端口绑定了才能接收报文socket.send(buf, port, address, callback)发送报文socket.on(message, handler)接收报文socket.on(error, handler)处理错误这一步极容易被忽略socket.close()关闭 socket释放端口。我用一个表格来对比 UDP 服务器和 UDP 客户端在代码上的实际差别行为UDP 服务器UDP 客户端创建方式dgram.createSocket(udp4)相同是否必须 bind必须要接收外来的报文可选不 bind 也能发但收不到响应调用 send可发服务器同样具备发送能力主要行为接收 message必须监听只有 bind 了才能收到响应典型场景被动等待请求并回包主动发起请求等待响应理解这个表格之后工具的逻辑就清楚了监听面板相当于一个常驻的 UDP 服务器发送面板则是一个用完即关的临时客户端。为了能收到响应发送面板发送前会自动 bind 一个随机本地端口这样对端服务器回包时报文能回到这个工具本身。2.3 单 socket 还是多 socket 的设计取舍第一版我图省事整个工具只维护了一个全局 socket。监听端口用它发送报文也用它。看起来节省资源实际用起来全是问题发送端每次都要切换目标地址本地端口却始终是同一个如果同时有多个服务端在跟你交互你根本分不清哪条报文是哪个服务端回的。更麻烦的是UDP 工具经常需要在一个端口上长期监听同时又往另一个端口发包全局单 socket 会让“监听”和“发送”这两个动作互相污染。所以最终设计是监听面板维护一个常驻服务器 socket由主进程持有发送面板每次发送时临时创建一个新 socketsend 成功之后立刻 close。虽然频繁创建 socket 会带来一点性能损耗但 UDP 本身是无连接的创建 socket 的开销远小于 TCP完全感知不到差异。而且每次发送使用新的本地端口天然避免了多个服务端回包时端口混淆的问题。3. Electron 三层架构怎么搭主进程、preload、渲染进程各管什么网络收发必须放在主进程原因有两点。其一渲染进程如果启用了nodeIntegration: false理论上就不能直接 require(dgram)其二即使你为了省事在渲染进程开 Node 集成一旦 socket 回调里抛异常整个渲染进程都可能崩溃。正确的做法是主进程持有网络 socket渲染进程只负责 UI两边通过 IPC 通信。这个分层也是 Electron 官方推荐的安全模型。3.1 项目初始化与 package.json我建了一个名为electron-udp的目录初始化项目并安装依赖mkdir electron-udp cd electron-udp npm init -y npm install --save-dev electronpackage.json 里唯一要改的关键字段是 main必须指向主进程入口文件{ name: electron-udp, version: 1.0.0, description: A simple Electron app for UDP client/server datagram testing, main: main.js, scripts: { start: electron . }, devDependencies: { electron: ^28.0.0 } }这里有个很容易踩的坑npm 默认的 main 字段是index.js如果你忘了改Electron 启动时会直接报Cannot find module index.js。第一次跑不起来基本都是这个原因。3.2 preload 里用 contextBridge 暴露安全的 IPC 接口Electron 的现代推荐做法是renderer 开启contextIsolation: true、nodeIntegration: false然后通过 preload 脚本用contextBridge.exposeInMainWorld把有限的 API 暴露给页面。这样页面里拿不到 Node 的全部能力只能调用我允许它调用的那几个函数。preload.js 长这样const { contextBridge, ipcRenderer } require(electron); contextBridge.exposeInMainWorld(udpApi, { startServer: (config) ipcRenderer.invoke(udp:start-server, config), stopServer: () ipcRenderer.invoke(udp:stop-server), sendDatagram: (config) ipcRenderer.invoke(udp:send, config), onServerMessage: (callback) { const handler (_event, payload) callback(payload); ipcRenderer.on(udp:server-message, handler); return () ipcRenderer.removeListener(udp:server-message, handler); } });这里用了ipcRenderer.invoke/ipcMain.handle这套异步 API比老的ipcRenderer.sendipcMain.on好用得多invoke 能直接拿到主进程返回的 Promise 结果错误也能通过 Promise rejection 抛回渲染进程。需要注意onServerMessage返回了一个取消监听的函数这一步很多人会漏。如果页面框架里有热更新或者组件重新挂载的机制重复注册 listener 会导致消息被回调多次界面上出现一模一样的好几行记录。做工具类应用时宁可多写两行清理逻辑也不要留隐患。3.3 主进程窗口创建main.js 里创建窗口的代码是标准模板但 webPreferences 的配置有一处必须注意const { app, BrowserWindow, ipcMain } require(electron); const dgram require(dgram); const path require(path); let mainWindow; function createWindow() { mainWindow new BrowserWindow({ width: 1024, height: 720, webPreferences: { preload: path.join(__dirname, preload.js), contextIsolation: true, nodeIntegration: false } }); mainWindow.loadFile(index.html); } app.whenReady().then(() { createWindow(); registerUdpIpcHandlers(); }); app.on(window-all-closed, () { if (process.platform ! darwin) { app.quit(); } });preload 路径必须用path.join(__dirname, preload.js)不能直接写字符串preload.js。因为 Electron 在打包成 asar 后相对路径的解析基准会变直接写裸文件名大概率找不到文件。这个问题在开发环境可能不会暴露一旦打包就出问题。4. 把数据报收发真正接进 Electron核心实现代码拆解有了上面的骨架接下来就是把 UDP 逻辑填进主进程。我按照功能拆成三个部分服务器启动与关闭、客户端发送、消息推送到界面。4.1 启动 UDP 服务器监听核心思路同一个工具只允许一个常驻服务器 socket。如果用户再次点击“启动监听”我会先把旧 socket 关闭再创建新的避免出现端口不释放导致下一次 bind 失败。let udpServer null; ipcMain.handle(udp:start-server, async (event, config) { if (udpServer) { udpServer.close(); udpServer null; } const socket dgram.createSocket(config.family udp6 ? udp6 : udp4); socket.on(message, (data, rinfo) { sendToRenderer(udp:server-message, { type: receive, time: new Date().toLocaleTimeString(), from: ${rinfo.address}:${rinfo.port}, text: data.toString(config.encoding || utf8), hex: data.toString(hex), size: data.length }); }); socket.on(error, (err) { sendToRenderer(udp:server-message, { type: error, time: new Date().toLocaleTimeString(), text: socket error: ${err.message} }); }); await new Promise((resolve, reject) { socket.once(listening, resolve); socket.once(error, reject); socket.bind(config.port, config.host || 0.0.0.0); }); udpServer socket; return { ok: true, port: socket.address().port }; });注意promise里我同时监听了listening和error两个一次性事件。如果端口被占用dgram 会触发error事件而不是抛异常只有通过这个 Promise 才能把错误信息正确地返回给渲染进程。刚开始写的时候我没做这个处理结果端口被占用时渲染进程那边毫无反应主进程控制台却悄悄打印了Error: listen EADDRINUSE排查了半天才发现是错误没被捕获。4.2 发送 UDP 数据报发送的逻辑同样放在主进程渲染进程只需要把目标 IP、端口、数据、编码格式传过来。ipcMain.handle(udp:send, async (event, config) { const socket dgram.createSocket(udp4); const buf config.hexMode ? Buffer.from(config.data.replace(/\s/g, ), hex) : Buffer.from(config.data, config.encoding || utf8); // 先绑定随机端口这样才能收到服务端的回复 socket.bind(0, 0.0.0.0, () { socket.send(buf, config.remotePort, config.remoteHost, (err) { if (err) { sendToRenderer(udp:server-message, { type: error, time: new Date().toLocaleTimeString(), text: send error: ${err.message} }); } else { sendToRenderer(udp:server-message, { type: send, time: new Date().toLocaleTimeString(), to: ${config.remoteHost}:${config.remotePort}, text: config.data, hex: buf.toString(hex), size: buf.length }); } socket.close(); }); }); });之所以在发送前调用socket.bind(0)是因为如果不 bind客户端虽然能发出报文但本地端口是内核临时分配的而且这个 socket 无法收到对端回复。bind 到 0 表示让内核分配一个空闲的临时端口这样当接收端回包时报文能正确地回到这个 socket。很多新手写的 UDP 客户端“发是发出去了响应收不到”问题就出在这个细节上。十六进制模式下的处理也提一下用户输入的01 02 ab之类的内容我先用正则去掉所有空白字符再交给Buffer.from(str, hex)解析。如果不先清理空白01 02这种带空格的输入会直接解析失败抛出的异常会让整个 IPC 调用返回一个奇怪的错误对象界面上根本看不懂。4.3 把数据实时推送到界面主进程向渲染进程推送数据只有一个关键方法webContents.send。我在 main.js 里统一封装了一个函数function sendToRenderer(channel, payload) { if (mainWindow !mainWindow.isDestroyed()) { mainWindow.webContents.send(channel, payload); } }加了isDestroyed()判断的原因是如果用户已经关闭了窗口但 UDP 服务器还在后台跑着Electron 默认关闭窗口不会自动退出整个进程尤其 macOS 上这种行为更明显这时候调用webContents.send会报一个Object has been destroyed的错误。这个错误不算致命但会污染主进程的异常日志让人误以为程序崩了。渲染进程收到消息后直接往记录列表里追加一行即可。这里我用了一个非常简单的方式把type为receive的条目靠左显示且文字标绿send的条目靠右显示且文字标蓝error的条目用红色显示。视觉上扫一眼就能区分收发。5. 实测阶段踩过的坑端口占用、防火墙、编码、以及 socket 生命周期代码写完后我进行了三轮实测本机回环收发、Windows 与 Linux 双机通信、十六进制数据收发。踩了四个比较有代表性的坑全部记录下来这些都是纯看文档学不到的经验。5.1 端口占用事件必须显式捕获这个问题我在 4.1 节已经提过一次但值得专门展开。很多人写 Node dgram监听listening和message事件就够了因为正常流程它们一定会触发。可一旦端口被其他程序占用dgram 不会像 HTTP 服务那样抛出同步异常而是触发error事件。如果这个事件没有监听器Node 会把错误当成未捕获异常直接抛出表现就是你的 Electron 应用瞬间退出完全没有提示。我的建议是每个 dgram socket 创建出来之后立刻挂一个完整的 error 监听器并且在里面把错误信息推送到界面。这样用户才知道“端口被占用”或者“权限不足”而不是一头雾水地看着应用闪退。另外bind操作放在一个 Promise 里同时监听listening和error能更干净地把错误带回调用方。5.2 Windows 防火墙对 UDP 入站报文的静默拦截本地回环测试一切顺利我以为大功告成结果拿到另一台 Windows 电脑上一跑发现局域网内其他设备发送到这台机器的 UDP 报文工具完全收不到。一开始我还怀疑是自己代码的问题甚至用 Wireshark 抓包确认了报文确实到达了网卡。排查到最后才发现Windows 防火墙默认阻止 UDP 入站连接而且这个阻止是静默丢包不像 TCP 那样会返回拒绝连接的错误。第一次启动应用时系统弹出的防火墙授权对话框被我不小心点了“取消”往后就再也不弹了。解决办法是到“Windows 安全中心 → 防火墙和网络保护 → 允许应用通过防火墙”把你打包后的 exe 或者开发模式下的 electron.exe 勾上专用网络和公用网络的权限。结合这一点我在工具里给了一个很实用的设计收发记录区域上方增加一个“网卡提示”如果用户填的监听地址是0.0.0.0而接收不到外部报文时顺手把防火墙排查建议写出来。这个提示才几行字但实际使用中能帮团队省掉非常多排查时间。5.3 文本编码与十六进制显示的取舍UDP 调试中经常遇到一个问题对方发来的是 GBK 编码的文本或者干脆是不可打印的二进制。我在设计数据展示区时同时保留了两列内容——原文和 Hex。原文直接用Buffer.toString(utf8)哪怕转出来是一堆乱码也无所谓因为旁边有十六进制可以对照。发送侧的处理则更关键如果用户选择“十六进制发送”程序必须以hex模式解析输入如果选择“文本发送”就用配置文件里指定的编码方式默认 UTF-8解析。这个选项必须显式暴露在界面上不能自动判断。因为01 02这个字符串你没法可靠区分它是十六进制数据描述还是纯文本内容。很多 UDP 调试工具在这个问题上做得非常反人类要么强制十六进制要么强制文本我的做法是提供一个下拉框让用户自己选默认文本模式更符合日常使用习惯。5.4 socket 关闭时机发送后立刻 close 会丢响应吗这是一个我原来担心的点客户端发送后立刻调用socket.close()这时候服务端的响应报文还没回来关闭 socket 会不会导致响应收不到实测发现UDP socket 的close()会立即释放本地端口之后到达的报文不会再被这个 socket 接收内核会直接回复一个 ICMP Port Unreachable 给对端。所以严格来说“发送后立刻关闭就收不到响应”这个担心是成立的。但在我的设计里发送 socket 和监听 socket 是分开的工具里的“监听”面板负责接收响应发送面板只是单纯的发送动作它不需要等响应。也就是说发送 socket 关闭后如果有响应报文回来会进入监听面板那个常驻 socket 里前提是监听端口和发送 socket 绑定的随机端口不是同一个显然不是。如果你的使用场景是“既要发送又要接收对端回复”建议不要用每次新建 socket 的方式而是把发送和接收合并到一个常驻 socket 上。但对我来说监听面板就是干这个活的分开反而更清晰。6. 真实使用场景验证以及这个工具怎么扩展成团队内部的标准调试利器工具做完之后我立刻用它验证了一个实际场景测试一台 NTP 时间服务器的响应。NTP 协议走 UDP 123 端口报文格式是 48 字节的固定结构。我在“发送”面板里用十六进制模式手动构造了一个标准的 NTP 请求报文填入目标服务器的 IP 和端口同时在“监听”面板绑定本机一个端口然后把 NTP 请求的源端口也指向这个监听端口。点击发送后不到一秒钟监听面板就收到一条 48 字节的响应报文Hex 栏里能看到完整的时间戳字段。整个过程不需要 Wireshark不需要命令行界面上一目了然调试效率提升非常明显。类似地我还测试过 GB28181 国标设备在非标准端口上的 UDP 信令交互。对方文档里只说“设备会上报心跳报文到中心服务器的 5060 端口”但实际上设备配置文件里还有好几个备用端口用这个工具逐个监听这些端口很快就能确认设备到底从哪个端口发数据。这种“广撒网监听多个端口”的诉求Wireshark 能做但不直观命令行 nc 一次只能监听一个端口而这个工具只要把监听面板复制两份就能同时盯住多个端口。最后说说扩展方向。当前版本只做到了“收发数据报”但其实还可以加入几个高频功能定时自动发送固定间隔向目标端口发送同一条报文用于压力测试或者保活场景相当于一个迷你版的 iperf3 UDP 打流工具。会话串联把同一个from地址的收发记录折叠成一组方便观察多轮交互的时序。保存为 pcap收到的数据报可以直接追加写入 pcap 文件方便后续用 Wireshark 做深入分析省去同时开两个工具的麻烦。我在实际使用中发现工具类应用最重要的不是功能多而是“启动快、界面清晰、出问题时能立刻定位”。Electron 开发这类工具确实占内存但胜在迭代快、跨平台一致这也是我最终坚持用它而不用原生 Qt 或者 Tkinter 的原因。如果你也经常被 UDP 联调折磨不妨照着这套架构花一个晚上自己写一个跑通之后你对 Electron 主进程和渲染进程的协作方式理解会远比看一百篇教程来得深。本文还有配套的精品资源点击获取