在局域网里传几百兆的文件很多人第一反应是开共享目录、插U盘或者临时架一个FTP。但有一类场景这几样都靠不住接收端是专用设备不方便映射盘符对方机器只开放了指定端口没有图形化交互入口又或者你必须把“传输结果”“文件校验值”一并记录下来。我前阵子就用C# WinForms写了一个TCP文件传输例子把这些需求全揉进一个带进度条的小工具里从选文件到推送完成一条链路解决。今天不贴半成品把协议设计、分片策略、界面交互和实测踩坑一次性讲透。无论是刚入门的WinForms新手还是想在内网做一个带界面的传输工具的开发者这篇文章都值得从头看完。最后你会得到一套能直接改着用的代码思路而不是只能跑Demo、一传大文件就崩的示例。1. 先判断自研TCP传输到底适合什么场景1.1 为什么不能直接拿现成的FTP或HTTPFTP和HTTP都能传文件但它们都有各自的“部署成本”。FTP要装服务端、要配账号目录、还要处理被动模式和防火墙放行现场设备一旦被限制端口基本没法用。HTTP上传要么搭一个Web服务要么找现成的文件网盘但你要在内网环境里主动推送到一台指定设备而不是等对方来下载这就很别扭。我的场景很简单一台运行着业务程序的专用主机平时没人在跟前开放一个TCP端口希望另一台机器能直接把升级包推过去。这个需求用FTP得管账号用HTTP得起服务而自写一个TCP客户端和服务端嵌在WinForms里反而最干净——发送端就是一个按钮接收端就是一个监听窗口逻辑完全可控。1.2 自研方案的边界在哪这里得先泼一盆冷水。TCP文件传输适合“可信局域网内、单点对单点或一对多、传输双方都能控制”的场景。如果目标是跨公网传文件我不建议自己写裸TCP更推荐直接用现成的HTTPS下载或同步工具因为公网环境要处理的路由、加密、NAT穿透问题不是一个小工具能扛住的。所以我自己做这个例子时范围就锁定在双方处于同一个内网端口可通传输内容不涉及高安全等级机密。加密能力可以通过后续加SslStream扩展但前提是先把传输流程跑通否则一上来就堆加密出了问题你分不清是协议错还是证书错。2. 协议是传文件的第一个坑粘包、半包和信封设计2.1 TCP是字节流不是消息管道很多新手第一次写TCP通信会默认“我发一次你就收一次”。这个理解是错的。TCP是流式协议数据像水管里的水一样源源不断流过去接收方根本不知道哪里是“一条消息”的起点和终点。发送方连续发两个包接收方可能一次读到了两包的内容这叫粘包发送方一包数据较慢到达接收方只读到前半段这叫半包。如果用生活化的比喻你把几封信用一条水流送出去对端收到的是一大坨湿透的纸他得自己凭信封的封皮判断哪几页属于同一封信。所以我们必须在应用层自己设计“信封”把边界画清楚。2.2 自定义信封固定包头 可选文件名我给每个数据包设计了一个固定长度的包头接收方先读这个固定长度读齐了再解析。下面的表格就是我实际用的一套格式。字段类型字节数说明魔数ushort2固定0xA5A5用于快速判断包起始是否正确命令byte10x01元数据0x02文件块0x03结束文件名长度ushort2只有元数据包有效文件总长度long8整个文件的总字节数包序号int4当前数据块从0开始编号包总数int4文件分块后的总块数数据长度int4当前块有效数据字节数0表示结束CRC32uint4当前数据块payload的CRC32校验值包头一共29字节。如果是元数据包命令0x01在包头后面再跟一段UTF-8编码的文件名字节长度由“文件名长度”字段告诉接收方。数据包命令0x02则是包头加原始文件字节。魔数是我比较坚持的字段。虽然前面接了固定长度理论上不会错位但一旦网络环境异常导致数据流错乱靠长度硬解会直接把后面所有数据都解歪。魔数就是一个快速判断点在调试和抓包时帮你把问题范围缩小。2.3 接收端怎么处理粘包和半包接收端的核心方法不是“读一次”而是“读满指定长度再继续”。我封装了一个ReadExactlyAsync方法它循环调用NetworkStream.ReadAsync直到读够目标字节数才返回如果中途读到0字节说明连接已关闭。private async Taskbyte[] ReadExactlyAsync(NetworkStream stream, int count, CancellationToken ct) { var buffer new byte[count]; int offset 0; while (offset count) { int read await stream.ReadAsync(buffer.AsMemory(offset, count - offset), ct); if (read 0) { throw new EndOfStreamException(连接被关闭或数据不完整); } offset read; } return buffer; }有了它接收方处理流程就规范了先读29字节包头解析出数据长度再继续用ReadExactlyAsync读payload。如果这次网络包里还残留下一个包的字节没关系它们会留在流缓冲区里下一轮循环继续读这就是对粘包的自然处理。半包则由ReadExactlyAsync内部的循环解决。只要所有发送都用“包头payload”的格式写接收端只用“读满包头读满payload”的格式读粘包半包问题就从机制上被排除了。3. 分片读取与进度计算不要把整个文件塞进内存3.1 一次读完整文件会出什么事初学者最常写的代码是File.ReadAllBytes然后把整个byte数组扔给NetworkStream。小文件没问题一旦文件到了几百MB甚至几个GB内存瞬间被撑爆。尤其是WinForms程序往往跑在一台普通办公电脑上后台还有数据库和浏览器抢内存一个500MB的文件用ReadAllBytes峰值内存轻松超过1GB界面当场卡顿甚至抛出OutOfMemoryException。更关键的是没有分片就没法做有效的进度反馈。你以为传完了其实只是“把文件读进内存了”实际网络发送还在慢慢排队进度条根本反映不了真实状态。3.2 用64KB缓冲区做流式分片我把分片大小设成64KB这个尺寸在TCP传输里算比较稳的选择不至于因为包太小造成大量包头开销也不至于因为包太大在应用层排队时占用太多内存。对高频传输场景也可以调到1MB但64KB对我来说兼容性最好。发送端流程是这样的先发送一个元数据包告诉对方文件名和文件总长度等待对方返回一个ACK命令0x80确认对方已准备好接收数据块然后开始循环读取文件流每读满一块就组装包头并发送最后发送结束包。const int chunkSize 64 * 1024; using var fs File.OpenRead(filePath); long total fs.Length; int totalBlocks (int)Math.Ceiling(total / (double)chunkSize); var buffer new byte[chunkSize]; int blockIndex 0; long sentBytes 0; while (true) { int bytesRead await fs.ReadAsync(buffer.AsMemory(0, chunkSize), ct); if (bytesRead 0) break; // 这里组装包头写命令0x02、包序号、包总数、数据长度、CRC32 await stream.WriteAsync(BuildDataHeader(blockIndex, total, bytesRead), ct); await stream.WriteAsync(buffer.AsMemory(0, bytesRead), ct); sentBytes bytesRead; ReportProgress(sentBytes, total); blockIndex; }有一个细节我刚开始写的时候栽过FileStream.ReadAsync返回的字节数不一定等于缓冲区大小尤其是接近文件末尾时可能只返回几千字节。很多人用读到的buffer整个长度去发送导致文件尾部多出一堆脏数据。所以必须用bytesRead作为实际发送长度而不是chunkSize。3.3 进度计算和总块数的数学关系因为提前知道文件total所以进度公式非常直白sentBytes / total * 100。有人会想先统计所有块的长度再一个个加没必要。发送端只要维护一个累计变量每写完一块就累加UI层拿到sentBytes和total直接算百分比。接收端也要累计已接收的文件字节数但接收端拿到的包序号可以用来检查数据块的连续性。如果收到的包序号不是预期的下一个说明中间丢了块或者顺序乱了此时应主动中断传输并提示错误不要继续拼写文件。这是校验文件完整性的第一道防线。4. 服务端与客户端谁监听、谁连接、谁来推送4.1 服务端TcpListener和异步Accept循环这个例子里接收方是服务端负责监听端口发送方是客户端主动推送文件。服务端用TcpListener监听显然不能在UI线程里同步Accept否则窗口会僵死。用异步Accept循环每个接入的TcpClient单独开一个处理任务。TcpListener _listener; readonly ListTcpClient _clients new(); public async Task StartAsync(int port, CancellationToken ct) { _listener new TcpListener(IPAddress.Any, port); _listener.Start(); while (!ct.IsCancellationRequested) { TcpClient client await _listener.AcceptTcpClientAsync(ct); lock (_clients) _clients.Add(client); _ HandleClientAsync(client, ct); } }我把每个客户端都存进List这样如果同一时间有多台发送端往这台接收设备推文件主界面能列出当前连接数量和每路连接的IP。实际项目里确实出现过两台上位机同时推送的情况不加列表的话根本不知道哪路连接在传什么文件。4.2 客户端TcpClient连接和超时控制发送端只需知道接收端的IP和端口然后调用TcpClient.ConnectAsync。注意连接动作一定要做超时控制否则如果IP不可达默认可能会卡很久。简单做法是用CancellationToken配合超时任务组合或者直接借助没有取消支持的.NET Framework时用Task.WhenAny模拟一个时间竞赛。连接的IP地址建议做成可配置项而不是写死。因为内网设备的IP可能因DHCP变化一个文本框加一个记住上次IP的配置文件就能避免每次改代码重新编译。发送端连上之后下一步是先填文件名、点发送按钮。连接动作和发送动作可以分开连接成功只是双方建立会话点在按钮之后再开始按协议传文件。4.3 连接断开的判断与清理TCP没有主动发给应用层的“断开事件”你需要自己在读写异常时判断。ReadExactlyAsync读到0字节、WriteAsync抛出IOException、SocketException这些都是断线信号。接收端在HandleClientAsync里用try/catch包住整个处理流程finally里把TcpClient从列表移除并释放防止连接泄漏。private async Task HandleClientAsync(TcpClient client, CancellationToken ct) { string remote client.Client.RemoteEndPoint?.ToString() ?? unknown; try { using var stream client.GetStream(); // 按协议读元数据、接收文件块、校验 } catch (Exception ex) { Log($[{remote}] 传输异常: {ex.Message}); } finally { client.Close(); lock (_clients) _clients.Remove(client); Log($[{remote}] 连接已释放当前连接数 {_clients.Count}); } }写到这里我想强调一个容易被忽略的点TcpClient和NetworkStream都是需要释放的。如果接收端处理完一个文件不关闭流连接会在半开状态下挂着端口越积越多。WinForms工具通常长期运行连接泄漏一天下来就能把端口耗尽。5. WinForms界面和异步进度条看起来正常比功能还难5.1 为什么不能用同步阻塞很多人把发送逻辑写在按钮点击事件里里面直接用NetworkStream.Write。文件一大UI线程就卡死在网络I/O上窗口拖不动进度条不刷新用户以为程序死了。解决思路是用async/await让I/O操作返回到线程池UI线程只在必要的时候更新界面。我建议把所有发送和接收方法都写成async Task点击事件用async void包一层。虽然async void在异常处理上不完美但WinForms事件天生是void签名这是为数不多能接受的用法。方法内部所有可能抛异常的地方都必须try/catch不要让它直接炸到事件外面。5.2 IProgress 是跨线程更新UI的正解WinForms的控件只能在UI线程操作异步方法继续执行时很可能在线程池线程直接改ProgressBar会抛跨线程异常。传统写法是Control.Invoke但更好的做法是IProgressT。var progress new Progress(long Sent, long Total)(v { progressBar.Maximum (int)(v.Total / 1024); progressBar.Value (int)(v.Sent / 1024); lblPercent.Text ${v.Sent * 100.0 / v.Total:F1}%; }); await SendFileAsync(client, filePath, progress, ct);ProgressT会自动把回调调度回创建它的同步上下文也就是UI线程所以回调里可以直接操作控件。这个机制比手写Invoke简洁太多也几乎不会出错。但有个性能问题如果每64KB就报告一次进度一个500MB的文件会触发八千多次UI回调界面会忙于刷新。我实际的处理是加一个节流器比如距离上次UI更新超过100毫秒才真正更新一次不仅进度条不卡CPU占用也降下来了。5.3 按钮状态和取消传输传输开始后必须把发送按钮、文件选择按钮全部禁用防止用户重复点击开启多个发送循环。传输结束或失败后再恢复。取消则用CancellationTokenSource点“取消”按钮时调用cancelTokenSource.Cancel()发送循环里的WriteAsync、ReadAsync会抛OperationCanceledException。这里有个细节取消后接收端可能已经写了一个残缺的.part文件所以接收端应该先把数据写入临时文件等接收到结束包且校验通过后再把临时文件改名成正式文件。如果中途取消直接删除.tmp文件即可。这样即使传了一半断电也不会留下一个“看起来像完整文件但实际损坏”的正式文件。6. 一次完整传输流程跑通从启动到文件校验6.1 双方交互的时序我按真实工具的运行顺序描述一下方便你对照验证自己的实现。接收端点击“开始监听”填入端口号比如5566服务端进入Accept循环状态栏显示“正在监听”。发送端输入接收端IP和端口点击“连接”连接成功后填写要发送的文件路径。点击“发送”发送端先写一个元数据包文件名、总长度等待接收端ACK。接收端解析元数据创建同名临时文件返回ACK。发送端进入分块循环不断写包头和数据块接收端逐个读取并写入临时文件并更新自身进度条。最后一个数据块发送完毕发送端写结束包接收端关闭写流。接收端对临时文件计算哈希或CRC与发送端传过来的校验值比对一致则改名为正式文件提示“传输完成”。发送端清理连接资源界面恢复初始状态。这套流程每一步都有明确的包命令对应调试时只要打印收到每个包的命令和序号就能知道卡在哪一步。6.2 结束包和文件校验不能省略的收尾我建议无论项目大小都加上结束包和CRC校验。结束包是一个命令0x03、数据长度为0的包头它告诉接收端“不要再等了”。接收端如果到了“包总数”那个数值还没收到结束包就认为传输不完整直接报错。CRC32计算简单、速度也够快我在每个数据块都算了一个接收端收到后对payload重新算一次不一致就立即中断。这能及时暴露错误而不是等整个文件传完才发现坏了浪费十几分钟重传。文件整体校验我一般选SHA256因为它碰撞概率远低于CRC32。既可以对整个文件流计算也可以在每个块里累计最终比对十六进制字符串。很多同事说没必要但我碰到过一次交换机链路不稳导致文件中间有错位没有整文件校验的话接收端根本发现不了最后程序跑起来才报异常排查成本远高于那几秒校验时间。6.3 日志记录没有日志的传输工具不值得用WinForms工具虽然小但最好在启动目录下留一个txt日志记录每次传输的时间、文件名、总字节数、分块数、校验值、对端IP、耗时。出现问题的时候管理员直接看日志就能判断是哪一方的问题而不是两头互相猜。我在发送端和接收端都写了Log方法用DateTime.Now.ToString(yyyy-MM-dd HH:mm:ss)做前缀。实测下来这个日志在定位“为什么进度条到了100%却提示失败”这类问题时极其管用。7. 避坑清单和进阶方向少走弯路才叫经验7.1 我踩过的几个高频坑第一防火墙拦截。服务端监听端口后Windows防火墙会弹窗如果误点取消客户端就会一直连接超时。排查这类问题先不要怀疑代码直接用“telnet IP 端口”测试端口是否通通就是代码问题不通就是防火墙或网络问题。第二端口占用。如果之前调试时程序崩溃没退出端口可能还在TIME_WAIT状态重启程序会报“地址正在使用”。解决办法代码里监听前先调用listener.ExclusiveAddressUse false并在启动时做一次try/catch提示而不是静默失败。第三ReadAsync返回值处理。前面已经反复强调必须根据返回的字节数判断实际读取长度。这个坑在发送端和接收端都会出现是最容易造成文件损坏的原因。第四每次收发不要修改同一个byte数组。发送端如果在写入NetworkStream的同时又继续读下一块到同一buffer网络层可能还没把数据发完就把它覆盖了导致包头和数据错乱。每块要么新分配数组要么写入后再复用但确保发送完成我用的是每块从大池子里取一个独立数组。第五调试时别用MessageBox弹错误。传输过程中弹窗会阻塞接收循环网络缓冲区堆满后直接造成假死。日志记录异常就够了或者简单写一行状态栏。7.2 断点续传当文件大到必须以“GB”为单位时如果文件经常超过几个GB断点续传几乎变成必需品。思路是接收端在临时文件旁边维护一个记录文件保存“当前已接收字节数”和“包序号”。发送端启动时先发送“查询偏移量”命令接收端返回继续传输的位置发送端用FileStream.Seek(offset, SeekOrigin.Begin)跳到断点处继续读。实现不算复杂但能让工具的使用体验上升一个档次。7.3 限速和批量任务局域网内偶尔会和其他业务抢带宽。我在发送循环里加了个简单的限速器根据设定的每秒最大字节数算出每块应该耗时多久发送完检查实际耗时不够就Task.Delay补足。代码只需十几行效果却很明显。批量任务则可以做一个队列发送端把多个文件依次入队循环从队列取文件、依次传完。接收端按文件名自动存到指定目录局域网内“一键同步整个包”就是这么做出来的。最后分享一个我自己的体会文件传输工具难的不是写发送和接收的代码而是把协议边界、内存占用、界面反馈、异常清理这些细节都考虑进去。你把上面这几层都补全这个C# WinForms TCP文件传输例子就不再是教学Demo而是一个能真正扔到现场用的工具。真等到被现场环境教育过几轮你就会明白稳定传输比花哨界面值钱得多。