简介：这份资源面向需要实现FTP文件上传功能的开发者，尤其适合正在学习C#网络编程、希望为上传过程加入可视化进度反馈的初中级程序员。实例围绕FTP协议的文件传输流程展开，涵盖建立连接、身份验证、切换工作目录、分块上传及进度计算等关键环节，并借助封装好的FTP帮助类提升代码复用性。压缩包共35个文件，以cs源码、resx与resources资源文件、config配置、exe可执行程序及sln解决方案为主，整体约78KB，结构完整，可直接打开运行调试。目前已有868人学习下载。读者可从中获得一套可运行的带进度条上传示例，理解已传字节与总字节的比例换算逻辑，并参考其中的错误处理与连接释放思路，将其迁移到自己的项目中，改善文件上传的交互体验。
1. 一个进度条背后，藏着 FTP 上传最容易翻车的三个细节
很多人第一次写 FTP 上传，代码跑通了，文件也传上去了，但界面上的进度条要么一动不动，要么直接跳到 100%，要么传到一半卡死却没有任何提示。问题不在 FTP 协议本身，而在于大多数人只调了一个storbinary就以为完事了，完全没处理分块读写、回调频率和异常中断这三件事。这份 FTP 上传实例（带进度条）要解决的就是这个场景：把文件上传从“能传”做到“传得可见、传得可控、传断了知道断在哪”。它适合两类人——正在做桌面端或工具类应用、需要给用户一个真实上传进度反馈的开发者，以及想搞清楚 FTP 数据连接和回调机制到底怎么配合的从业者。下面按“先跑通、再拆参数、最后排坑”的顺序，把这份实例里的关键实现和边界条件讲透。
2. FTP 上传实例的核心机制：数据连接、分块读写与回调时机
2.1 为什么不能直接storbinary一把梭
Python 的ftplib里，storbinary(cmd, fp, blocksize)确实支持传入一个文件对象，内部会按blocksize循环读取并发送。但问题在于：它默认不给你任何中间回调。你只能在调用前后各打一个时间戳，进度条自然只能从 0 跳到 100。常见做法是自己接管读取循环，用transfercmd拿到数据连接后手动sendall，每发一块就更新一次进度。这样做的代价是要自己处理连接关闭和异常，但换来的是对进度粒度的完全控制。
另一个容易被忽略的点是 FTP 的“双连接”模型：控制连接负责命令交互，数据连接负责实际传输。transfercmd('STOR filename')会返回一个数据 socket，你必须在这个 socket 上写数据，写完close()，然后再从控制连接读226 Transfer complete。如果顺序错了，比如先读响应再关数据连接，就会卡在recv上等一个永远不会来的响应——这是进度条“卡在 99%”最常见的根因。
2.2 分块大小的选择：不是越大越快
分块大小直接决定进度回调的频率和内存占用。设得太小（比如 1KB），回调太频繁，UI 线程被刷爆；设得太大（比如 8MB），进度条会一格一格跳，用户体验反而差。我一般用 64KB 到 256KB 之间，具体看网络 RTT 和文件大小。下面是一个可复现的最小实现，把分块、回调和收尾都写全了：
import ftplib import os def upload_with_progress(host, user, passwd, local_path, remote_path, blocksize=128 * 1024, on_progress=None): total = os.path.getsize(local_path) sent = 0 ftp = ftplib.FTP(host, timeout=30) ftp.login(user, passwd) ftp.voidcmd('TYPE I') # 二进制模式，必须显式设置 with open(local_path, 'rb') as fp: conn = ftp.transfercmd(f'STOR {remote_path}') try: while True: chunk = fp.read(blocksize) if not chunk: break conn.sendall(chunk) sent += len(chunk) if on_progress: on_progress(sent, total) # 回调里只做轻量更新 finally: conn.close() ftp.voidresp() # 读 226，确认服务端落盘 ftp.quit() return sent这段代码的关键在三个位置：voidcmd('TYPE I')确保二进制模式，否则文本模式下换行符会被转换，文件大小对不上；transfercmd之后所有写操作都在conn上，控制连接此时是“挂起”状态；voidresp()必须在conn.close()之后调用，顺序反了就会死等。on_progress回调里不要做重活，只更新变量或发信号，真正的 UI 刷新交给主线程，否则回调频率一高就会拖慢传输本身。
2.3 进度回调的线程安全与节流
如果这个上传跑在后台线程，回调直接操作 UI 控件会触发跨线程异常。常见做法是回调里只把(sent, total)塞进一个队列或发一个信号，由 UI 线程定时取。另一个实用技巧是节流：不是每块都回调，而是按时间间隔（比如 100ms）或按百分比变化（比如每 1%）才触发一次。下面是一个简单的节流包装：
import time class ProgressThrottle: def __init__(self, callback, min_interval=0.1): self.callback = callback self.min_interval = min_interval self.last_time = 0 def __call__(self, sent, total): now = time.time() if now - self.last_time >= self.min_interval or sent == total: self.last_time = now self.callback(sent, total)min_interval设 0.1 秒是个经验值，既能保证进度条看起来连续，又不会让回调成为瓶颈。注意sent == total这个条件不能省，否则最后一块可能因为节流被吞掉，进度条停在 99% 不动——这个坑我在早期项目里踩过不止一次。
3. 把实例跑起来：环境、参数与三种典型接入方式
3.1 最小可运行环境与依赖确认
这份实例只依赖 Python 标准库的ftplib和os，不需要额外装包，这是它比较省心的地方。但服务端得先准备好：一个支持被动模式的 FTP 服务，以及一个有写权限的账号。本地验证时，我一般先用ftp命令行工具确认三件事——能登录、能put一个小文件、pasv模式能通。命令行能通而代码不通，问题基本都在代码的参数上，不在网络。
# 先用系统自带客户端做连通性确认 ftp -p <host> # 登录后依次执行 binary put test.txt bye-p表示被动模式，现在绝大多数服务端默认走被动，主动模式在 NAT 后面基本不可用。如果命令行put成功而代码失败，优先检查代码里有没有漏掉TYPE I，以及transfercmd的返回值有没有正确关闭。
3.2 参数表：每个值改了会发生什么
| 参数 | 常用值 | 改大后的影响 | 改小后的影响 |
|---|---|---|---|
blocksize | 128KB | 回调变稀、内存占用上升 | 回调变密、系统调用增多 |
timeout | 30s | 卡死时等更久才报错 | 网络抖动时误判超时 |
min_interval | 0.1s | 进度条更新变卡顿 | 回调过频拖慢传输 |
| 被动端口范围 | 服务端配置 | 需同步放行防火墙 | 端口不够用导致连接失败 |
timeout这个参数特别值得说：它管的是控制连接和数据连接的单次阻塞时间，不是整个传输的总时长。大文件传输时，只要每块数据在timeout内能发出去就不会触发，所以设 30 秒对慢速链路也够用。真正要防“传一半卡死”，靠的是外层加一个总时长监控或心跳，而不是把timeout调小。
3.3 三种接入方式：脚本、桌面工具、服务端批处理
第一种是纯脚本调用，适合定时任务或运维场景，直接把上面的upload_with_progress包一层main就行。第二种是桌面工具，把回调接到进度条控件上，注意用 2.3 的节流包装。第三种是服务端批处理，多个文件排队上传时，进度要按“总字节数”而不是“文件个数”算，否则大小文件混在一起时进度条会跳得很怪。批处理场景下我一般维护一个(已完成字节, 总字节)的全局计数，每个文件的分块回调往里累加，这样整体进度才是线性的。
total_bytes = sum(os.path.getsize(p) for p in file_list) done_bytes = 0 def on_file_progress(sent, total): global done_bytes # sent 是当前文件已发字节，换算成全局进度 overall = done_bytes + sent update_ui(overall, total_bytes) for path in file_list: upload_with_progress(..., on_progress=on_file_progress) done_bytes += os.path.getsize(path) # 当前文件完成后累加基数这里有个细节：done_bytes的累加必须放在上传成功之后，如果中途抛异常，基数不能加，否则重试时进度会虚高。批处理里每个文件独立建连还是复用连接，取决于服务端对并发和空闲连接的限制，复用连接省握手但异常后状态难恢复，我倾向每个文件独立连接，简单可控。
4. 避坑与排查：进度条不动、卡死、传一半失败的真实原因
4.1 进度条从 0 直接跳到 100%
现象是回调只被调用了一次，且sent直接等于total。原因通常是用了storbinary而没接管读取循环，或者blocksize被设成了大于文件大小的值。解决方法是确认走的是transfercmd手动循环，并把blocksize控制在 64KB 到 256KB 之间。另外检查回调是不是被节流逻辑误吞——如果min_interval设得过大而文件又小，确实可能只触发首尾两次。
4.2 卡在 99% 或最后一块不更新
现象是进度条停在接近满格的位置，程序不报错也不结束。原因基本是conn.close()和voidresp()的顺序问题，或者最后一块数据发完后没有正确关闭数据连接，导致服务端一直等不到 EOF，226响应永远不来。解决方法是严格按“发完数据 →conn.close()→voidresp()”的顺序执行，并在finally里保证conn一定被关闭。还有一种少见情况是节流把最后一块吞了，参考 2.3 里sent == total的强制触发。
4.3 大文件传到一半报Broken pipe或超时
现象是传输进行到某个百分比后抛异常，服务端日志显示连接被重置。原因多半是服务端的空闲超时或被动模式端口范围不够，也可能是中间网络设备对长连接做了清理。解决方法是先确认服务端被动端口范围足够大，再在客户端加断点续传能力——FTP 支持REST命令指定偏移量，配合APPE或STOR可以从断点继续。不过断点续传要求服务端支持REST，接入前先用命令行rest验证一下。
4.4 中文文件名或路径导致上传失败
现象是英文名文件正常，中文名文件报550或传上去名字乱码。原因是 FTP 协议本身不规定文件名编码，服务端和客户端的默认编码可能不一致。解决方法是登录后执行OPTS UTF8 ON（如果服务端支持），并在ftplib里显式设置ftp.encoding = 'utf-8'。如果服务端是老式实现不支持 UTF-8，就只能约定用英文名或做转码映射，这一点没有通用解，得看服务端能力。
4.5 回调里更新 UI 导致程序无响应
现象是上传开始后界面卡死，进度条不刷新，传输速度也明显变慢。原因是回调在传输线程里直接操作了 UI 控件，触发了跨线程竞争或锁等待。解决方法是用队列或信号把进度数据转到 UI 线程，回调本身只做入队操作。如果用的是某个桌面框架，确认它的跨线程更新机制是信号槽还是invoke，别在回调里直接改控件属性。
5. 进阶技巧：用REST做断点续传并验证进度准确性
断点续传是这份实例往上走一层最实用的扩展。核心思路是上传前先查远端文件大小，用REST把数据连接偏移到该位置，本地文件也seek到同一偏移，然后继续发。下面是一个带续传判断的片段：
def remote_size(ftp, path): try: return ftp.size(path) # 部分服务端不支持 SIZE，会抛异常 except ftplib.error_perm: return 0 def upload_resume(ftp, local_path, remote_path, blocksize=128*1024): offset = remote_size(ftp, remote_path) local_size = os.path.getsize(local_path) if offset >= local_size: return # 远端已完整，跳过 with open(local_path, 'rb') as fp: fp.seek(offset) conn = ftp.transfercmd(f'STOR {remote_path}', rest=offset) try: while True: chunk = fp.read(blocksize) if not chunk: break conn.sendall(chunk) finally: conn.close() ftp.voidresp()rest=offset是transfercmd的参数，它会先发REST offset再发STOR。注意SIZE命令在 ASCII 模式下返回的是转换后的大小，所以前面TYPE I必须已经设置过，否则偏移量会对不上。验证进度准确性有个笨但有效的办法：上传完成后用SIZE比对远端和本地字节数，再下载回来做一次哈希比对。我一般在小文件上做哈希，大文件只比字节数加抽样校验，全量哈希太耗时。
从那以后我每次接 FTP 上传需求，都会先把“分块大小、回调节流、关闭顺序”这三项写成检查清单过一遍，再动手写业务逻辑。进度条这东西，用户看到的是一个小动画，背后其实是连接状态机有没有被正确对待。希望帮到你。
本文还有配套的精品资源，点击获取
