简介：这是一份面向VC++开发者的FTP客户端实现源码包，源自Visual C++环境下的实际调试与使用项目，适合学习FTP协议、MFC界面开发及网络编程的初学者。压缩包共26个文件，以h头文件与cpp源文件为主，辅以ico图标、bmp工具栏位图、rc资源脚本及dsp/dsw工程文件，涵盖连接管理、上传下载、站点配置和界面交互等模块，结构简洁便于阅读。目前已有185人学习下载。通过阅读FtpTransfer.cpp、MainFrm.cpp及各视图类代码，可掌握FTP基本命令（USER、PASS、CWD、LIST、PUT、GET）的封装方式，理解套接字通信、文件传输进度反馈与异常处理技巧，并了解MFC单文档应用程序的工程组织方法。由于代码量不大且经过调试，适合作为课程设计或入门网络编程的参考模板。
1. 用 VC 写 FTP 上传下载工具，先拆开标题里藏着的工作量
一个做着 ERP 老系统的朋友，最近的活是从 FTP 服务器拉气象文件、传备份包，VC6 工程里加一个上传下载功能，网上搜来搜去都是“FTP.zip_vc FTP 上传_vc FTP下载_vc ftp上传”这种资源包标题，点进去要么缺头文件，要么编译不过。真正接手这件事的人，要解决的其实是三件事：选对 API、把上传下载跑通、把生产环境里那些断线和乱码问题提前堵住。这篇笔记就是按这个顺序写的，用 VC 能直接编译的 WinINet API 讲一套完整落地路径。适合正在维护老 MFC 工程、或者要在新 VC 项目里快速加 FTP 能力的人，新手能照抄代码，熟手可以重点看参数边界和踩坑记录。
2. 选型与协议边界：VC 里挂 FTP 到底用哪套 API 才不返工
FTP 客户端的实现方式多，VC 里常见的有三条路：MFC 的 CInternetSession 封装、裸 WinINet API、以及 libcurl 之类第三方库。很多老工程默认走了 CInternetSession，最后却卡在自定义命令和错误处理上。这一章先讲清楚为什么我推荐裸 WinINet，再交代主动被动模式、超时和字符集这几个在写业务前必须定死的参数。
2.1 CInternetSession 与 WinINet：封装程度决定了你要背哪些锅
CInternetSession、CFtpConnection 这套 MFC 封装，把 InternetOpen、InternetConnect、FtpOpenFile 这些句柄操作都包成了类方法，写个简单上传确实快。但封装带来两个问题：第一，很多底层选项没暴露到类接口里，比如要在连接级设置超时、要挂 WinINet 状态回调，得绕回 InternetSetOption 操作句柄，等于还得懂底层；第二，MFC 对 FTP 错误码的处理太“干净”，GetLastError 拿到的信息经常不够定位问题，调试时你猜不到服务端到底回了 550 还是 425。我用过两个项目之后，就改成直接调 WinINet API 了——反正 VC6 也自带 wininet.lib，不用引第三方，编译出来体积也小。
选裸 API 的另一个理由是后续功能扩展。标题里这类工具，做到后面几乎都会加“ftp监控”目录变化、断点续传、APPE 追加写这些需求。WinINet 的 FtpCommand 可以发任意 FTP 命令，REST、RNFR、RNTO、APPE 都能自己控制。换成 CInternetSession，表面省事，真到要发原始命令时你还得再开一层封装，反而重复劳动。
2.2 主动模式与被动模式：服务端在哪边，参数就往哪边调
FTP 有两种数据连接建立方式。主动模式（PORT）是客户端开一个监听端口，把地址告诉服务端，让服务端主动连回来；被动模式（PASV）是服务端开好数据端口，客户端再连过去。现在绝大多数部署环境里，客户端在 NAT 后面或者防火墙后面，服务端在网络另一头，主动模式的数据连接基本建立不起来——服务端连不回你的内网 IP，于是传输卡在半路，表现就是“列表能列，下载传到一半就超时”。所以我的习惯是：InternetConnect 里显式加 INTERNET_FLAG_PASSIVE，不依赖任何默认值。
主动模式不是没用。有些很老的 FTP 服务端（尤其是内网仿真环境里对端是 ensp 配出来的路由器 FTP 模块）对 PASV 支持有缺陷，被动模式握手怪怪的，这时反而是切主动模式能跑通。判断方法很朴素：同一个文件，切换 dwFlags 里的 INTERNET_FLAG_PASSIVE，看哪边稳定跑完。生产环境我一般默认被动，遇到 425 再切主动，把这个开关做成配置项，而不是写死。
2.3 连接超时、字符集与重试：正式写业务前的三个底线参数
正式写上传下载前，我把下面这段当作连接层的“地基”。它完成了会话建立、FTP 登录、超时设置三件事：
#include <wininet.h> #pragma comment(lib, "wininet.lib") HINTERNET hSession = InternetOpen( TEXT("FtpClient/1.0"), // 自定义 User-Agent，FTP 握手时可见 INTERNET_OPEN_TYPE_PRECONFIG, // 跟随系统网络配置 NULL, NULL, 0); DWORD dwTimeout = 15000; // 15 秒，单位毫秒 InternetSetOption(hSession, INTERNET_OPTION_CONNECT_TIMEOUT, &dwTimeout, sizeof(dwTimeout)); InternetSetOption(hSession, INTERNET_OPTION_RECEIVE_TIMEOUT, &dwTimeout, sizeof(dwTimeout)); InternetSetOption(hSession, INTERNET_OPTION_SEND_TIMEOUT, &dwTimeout, sizeof(dwTimeout)); HINTERNET hFtp = InternetConnect( hSession, TEXT("192.168.1.10"), 21, // 服务器地址与控制端口 TEXT("ftpuser"), TEXT("ftppass"), // 账号密码 INTERNET_SERVICE_FTP, 0, INTERNET_FLAG_PASSIVE); // 被动模式，见 2.2逻辑说明：InternetOpen 第一个参数是客户端标识，FTP 服务器日志里会记录这个字符串；第二个参数 INTERNET_OPEN_TYPE_PRECONFIG 表示读系统网络配置，两个 NULL 分别是代理名和代理绕过表，不需要就置空。InternetSetOption 在会话句柄上设置三类超时：连接建立超时、数据接收超时、数据发送超时，这里统一给了 15 秒。注意这组超时是“单次操作”的超时，不是整个文件传输的超时，大文件传着传着长时间没网络活动就会触发。InternetConnect 返回的 hFtp 是登录后的 FTP 会话句柄，后续 FtpPutFile、FtpGetFile、FtpOpenFile 都挂在它下面。如果返回 NULL，GetLastError 大概率能告诉你 530 登录失败还是 12002 连接超时。
除了超时，字符集是第二个最容易埋雷的底线参数。WinINet 的窄字符版本把远程文件名当透明字节流，不做编码转换。GBK 服务端列目录，你用 ANSI 读是正常中文；UTF-8 服务端列目录，你用 ANSI 读就是乱码。这个问题没有 API 能自动解决，只能在配置里加一个“服务端编码”字段，让实施的人选 UTF-8 还是 GBK。重试策略相对简单：对网络抖动类错误（12002、12019），间隔 500ms、2 秒、5 秒重试三次；对 550、530 这种逻辑错误，直接返回，不重试，重试了也是白费。
3. 跑通 FTP 上传：从 FtpPutFile 最小命令到带进度回调的完整链路
上传是标题里排在后面的动作，但实际开发时大多数人先做上传，因为上传逻辑比下载多一层“要不要覆盖、怎么命名”的考虑。这一章先给最小可跑代码，再给分块写和进度的正解，最后落在临时文件名加原子替换上——这一套组合拳能让你在生产目录里少挨骂。
3.1 最小上传代码：FtpPutFile 的三个关键参数
FtpPutFile 是做 FTP 上传最省事的入口，一条调用把本地文件整个推到远程。先看最小形态：
BOOL bOK = FtpPutFile( hFtp, // 来自 InternetConnect 的 FTP 会话句柄 TEXT("C:\\data\\local.bin"), TEXT("/upload/remote.bin"), FTP_TRANSFER_TYPE_BINARY, // 二进制模式；文本文件才用 ASCII 0); // 同步执行，不需要回调上下文 if (!bOK) { DWORD err = GetLastError(); // 550 表示目录无权限或磁盘满，12019 表示数据连接中断 }逻辑说明：FtpPutFile 内部做了两件事：按远程路径 FtpOpenFile 打开一个写入句柄，再把本地文件分块送过去。第三个参数是传输模式，FTP_TRANSFER_TYPE_BINARY 对二进制文件、压缩包、图片都必须用；如果选了 ASCII，Windows 的换行符会被转换，图片传过去直接损坏。第四个参数 0 表示用默认上下文，同步执行完才返回。注意这个函数没有任何进度回调能力，传大文件时界面只能干等，这是它最大的局限。
3.2 要进度时改用 FtpOpenFile + FtpWrite：分块上传怎么组织
生产环境传 50MB 以上的文件，没有进度提示基本等于黑匣子。这时我不用 FtpPutFile，改成 FtpOpenFile 拿远程写入句柄，配合本地文件循环读、循环写，自己算进度。核心代码如下：
HINTERNET hRemote = FtpOpenFile( hFtp, TEXT("/upload/remote.bin"), GENERIC_WRITE, // 以写入模式打开远程文件 FTP_TRANSFER_TYPE_BINARY, 0); if (hRemote == NULL) { // GetLastError 为 12003 时，可从服务端响应文本里看到具体错误 return -1; } HANDLE hLocal = CreateFile( TEXT("C:\\data\\local.bin"), GENERIC_READ, FILE_SHARE_READ, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL); BYTE buf[8192]; // 8KB 缓冲，弱网环境下比较稳 DWORD cbRead = 0; LONGLONG totalBytes = 0; while (ReadFile(hLocal, buf, sizeof(buf), &cbRead, NULL) && cbRead > 0) { DWORD cbWritten = 0; if (!FtpWrite(hRemote, buf, cbRead, &cbWritten)) { // 12019: 数据连接被对端断开，记录已写字节数用于续传 break; } totalBytes += cbWritten; // 可以用 totalBytes / 本地文件大小 计算百分比，回刷界面 } InternetCloseHandle(hRemote); CloseHandle(hLocal);逻辑说明：FtpOpenFile 的第二个参数是远程路径，第三个参数 GENERIC_WRITE 告诉 WinINet 这是上传句柄，之后只能用 FtpWrite 写。循环里 ReadFile 从本地读 8KB，FtpWrite 把它送到远程，第四个参数返回实际写入字节数。每次 FtpWrite 成功后就累加，这个累计值就是进度条的数据来源。为什么不用 InternetWriteFile 而用 FtpWrite？FtpWrite 是 WinINet 给 FTP 句柄封装的专用写入，实际底层也会调 InternetWriteFile，但参数语义更清晰。缓冲区选 8KB 是折中：太小会让数据连接上全是小包，太大在弱网丢包重传时反而拖慢速度。高带宽专线可以调到 32KB，再往上收益就很有限了。
这段代码还有一个隐藏好处：如果 FtpWrite 在中途失败，totalBytes 就是已经传进去的字节数。后面做断点续传时，这个值可以直接用作 REST 或者追加判断的基准。
3.3 上传的重试与覆盖策略：临时文件名与原子替换
直接往目标路径覆盖上传，是生产事故的高发点：传了一半失败，远程文件变成半截，下一次上传又从这里开始，修复成本翻倍。我一般用“临时文件 + 改名”的方式避开这个坑。先上传到带 .upload 后缀的临时名，传完后用 RNFR/RNTO 两条 FTP 命令做原子改名：
// 第一步：先传成临时文件 BOOL bUp = FtpPutFile( hFtp, TEXT("C:\\data\\local.bin"), TEXT("/upload/remote.bin.upload"), // 临时名，避免污染正式文件 FTP_TRANSFER_TYPE_BINARY, 0); if (!bUp) { return -1; } // 第二步：RNFR 指定要改名的源文件 BOOL bRNFR = FtpCommand( hFtp, FALSE, 0, TEXT("RNFR /upload/remote.bin.upload"), NULL); if (!bRNFR) { return -2; } // 第三步：RNTO 指定目标名，这两个命令必须连着用 BOOL bRNTO = FtpCommand( hFtp, FALSE, 0, TEXT("RNTO /upload/remote.bin"), NULL); if (!bRNTO) { // 目标文件可能被占用或权限不足，远程排查 550 }逻辑说明：FtpCommand 的第一个参数是执行标志，FALSE 表示发完命令等响应就返回，不进入数据传输状态；第四个参数是原始 FTP 命令字符串。RNFR 和 RNTO 是一对状态相关命令，中间不能夹其他命令，否则服务端会返回“RNFR 状态未激活”的 503 错误。这种先传临时名再改名的做法，保证正式目录里永远只有完整文件，要么是旧的，要么是新的，不会出现半截文件。对不支持改名覆盖的服务端，只能在覆盖前先删远程旧文件，但删除和上传之间窗口期，远程目录会短暂缺文件——接受这个限制，或者干脆用带时间戳的版本文件名。
关于重试：如果临时文件传输失败，远程残留的半截 .upload 文件，下一次上传前先尝试删除，或者传一个 .upload.tmp 再在成功时连续改两次名。我实际项目中是启动时扫描远程目录里当天残留的 .upload 后缀文件，统一删除，省得积累垃圾。
4. FTP 下载落地与状态码排查：三个高频踩坑的定位顺序
上传跑通后，下载就是对偶操作，但踩坑点不一样：下载容易在“本地已存在文件被覆盖”和“远程目录列不出来”这两个地方翻车。这一章先写最小下载代码和目录列表，然后给三个高频踩坑记录，全部按现象、原因、解决的顺序写。
4.1 下载的最小对称流程：FtpGetFile 与 FtpRead 两条路
FtpGetFile 是最简单的下载入口，和 FtpPutFile 正好对称：
BOOL bOK = FtpGetFile( hFtp, TEXT("/download/remote.bin"), TEXT("C:\\data\\local.bin"), FALSE, // FALSE: 本地已存在同名文件时返回失败 FTP_TRANSFER_TYPE_BINARY, INTERNET_FLAG_PASSIVE); // 与连接时的被动模式保持一致 if (!bOK) { DWORD err = GetLastError(); // ERROR_FILE_EXISTS: 本地文件已存在 // 12002: 连接超时 }逻辑说明：第四个参数 FALSE 是这张代码的安全阀。很多初版代码这里写 TRUE，后果就是每次启动工具都把本地正在用的文件悄悄覆盖掉。我建议永远用 FALSE，让调用方显式决定先删旧文件还是改新文件名。第五个参数二进制模式，第六个 INTERNET_FLAG_PASSIVE 要和控制连接的保持一致，否则数据连接行为不可预期。
如果下载要进度，还是走 FtpOpenFile 加 InternetReadFile 的分块路线：
HINTERNET hRemote = FtpOpenFile( hFtp, TEXT("/download/remote.bin"), GENERIC_READ, FTP_TRANSFER_TYPE_BINARY, 0); if (hRemote == NULL) return -1; HANDLE hLocal = CreateFile( TEXT("C:\\data\\local.bin"), GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL); BYTE buf[32768]; DWORD cbRead = 0; while (InternetReadFile(hRemote, buf, sizeof(buf), &cbRead) && cbRead > 0) { DWORD cbWrite = 0; WriteFile(hLocal, buf, cbRead, &cbWrite, NULL); } InternetCloseHandle(hRemote); CloseHandle(hLocal);这里有一个必踩的坑：远程句柄必须用 InternetReadFile 读，而不是 ReadFile。HINTERNET 句柄不是普通的 Win32 文件句柄，直接传给 ReadFile 会得到句柄无效的错误。每读到一块就 WriteFile 落盘，好处是即使中途断线，本地已有的字节也能保留下来做断点续传。
4.2 远程目录列表：FtpFindFirstFile 的字段筛选与目录判断
很多下载需求是“把目录里所有新文件拉下来”，这就必须先列目录。WinINet 用 FtpFindFirstFile 加 InternetFindNextFile 完成遍历：
WIN32_FIND_DATA ffd; HINTERNET hFind = FtpFindFirstFile( hFtp, TEXT("/data/*"), // 通配符查找，* 表示全部文件 &ffd, 0, 0); if (hFind != NULL) { do { BOOL bDir = (ffd.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY) != 0; if (!bDir) { // ffd.cFileName 是文件名，ffd.nFileSizeLow/High 是大小 // 做“ftp监控”时，记录文件大小和最后修改时间到本地清单 } } while (InternetFindNextFile(hFind, &ffd)); InternetCloseHandle(hFind); }逻辑说明：FtpFindFirstFile 的第二个参数是远程路径加通配符，第三个参数返回一个 WIN32_FIND_DATA，字段含义和本地目录遍历一致。dwFileAttributes 里的 FILE_ATTRIBUTE_DIRECTORY 位区分文件和目录，对目录再递归调用 FtpFindFirstFile 就能整棵树遍历。这里有个和 2.3 呼应的坑：窄字符版本下，如果服务端是 UTF-8 编码，cFileName 拿到的中文名会乱码。解决办法是统一用宽字符版本接口（带 W 后缀），拿到宽字符后自己按 UTF-8 转成 ANSI，或者反过来。千万别在窄字符和宽字符之间 Cocos2d 式乱转，转一次错一次。
要做“ftp监控”目录变化，就在这段代码外面套一个轮询循环：周期性重新列目录，把文件名、大小、修改时间存进一个本地映射，和上一次比对，出现新增或大小变化就是需要下载的文件。这个方案朴素但可靠，比监听 FTP 通知事件现实得多。
4.3 状态码定位：三个高频踩坑记录
这一节写三个我在实际排查中反复遇到的下载问题，每一条都按“现象 → 原因 → 解决”的顺序给，方便你照着对照。
第一条，现象：下载大文件传到 30% 就停住，最后 GetLastError 返回 12002 或 12019。原因：12002 是 WinINet 超时，12019 是数据连接被断开。多半是服务端或中间防火墙的空闲连接超时时间比你的传输间隔短，网络上有几十秒没有数据包，连接就被清了。解决：把 INTERNET_OPTION_RECEIVE_TIMEOUT 调到 60 秒甚至 120 秒，并且把读缓冲分块控制好，不要让大块数据一口气憋在服务端。
第二条，现象：FtpGetFile 返回 550，本地日志只有一行“文件不可用”。原因：远程路径写错、文件实际不在该目录、或者当前账号对该目录没有读权限。有些 FTP 服务端为了隐藏目录，文件不存在时也回 550。解决：先用 4.2 的 FtpFindFirstFile 列出完整目录，把服务端返回的文件名字节原样拷贝出来和你的路径比对——肉眼看着一样的输出，可能多了一个不可见空格或者换行，用十六进制看最稳。
第三条，现象：下载调用报“句柄状态不正确”，错误码 12013。原因：我在 4.1 说过，HINTERNET 句柄被当作普通文件句柄用了；另一种更隐蔽的是，下载还没结束就把 hRemote 关闭，或者把 hFtp 和 hRemote 的操作顺序搞反了。解决：检查代码里有没有用 ReadFile 读网络句柄，改成 InternetReadFile；再确认 InternetCloseHandle 只关对应的句柄，FTP 会话句柄 hFtp 要在所有文件句柄关闭之后再关。这个坑新手看文档根本想不出来，因为错误码提示实在抽象。
再补充一个 530 登录失败的场景：服务端配了 IP 白名单，客户端 IP 变了就直接拒登，和账号密码无关。这个查法不是看代码，是看服务端日志里的登录来源 IP。
5. 往生产走：用断点续传收尾，顺便治一治 FTP 的脾气
下载和上传都跑通后，生产环境真正拉开差距的是大文件断了怎么办。这一章给断点续传的最小实现，以及分块与超时的最后一点平衡技巧。
5.1 REST 指令续传：下载中断后不必从头开始
FTP 的 REST 命令用于设置传输偏移量，后面跟 RETR 时，服务端从指定位置继续发数据。WinINet 里用 FtpCommand 发 REST，再走 FtpOpenFile 下载，很多服务端能识别这个偏移并配合。代码思路如下：
// 本地已下载 102400 字节，续传前先发 REST 指令 TCHAR szCmd[64]; _stprintf(szCmd, TEXT("REST %d"), 102400); BOOL bRest = FtpCommand(hFtp, FALSE, 0, szCmd, NULL); if (bRest) { HINTERNET hRemote = FtpOpenFile( hFtp, TEXT("/download/remote.bin"), GENERIC_READ, FTP_TRANSFER_TYPE_BINARY, 0); // 之后 FtpOpenFile 内部发 RETR，服务端会从偏移处开始发送 }逻辑说明：REST 必须紧跟在下载命令之前发送，中间不能有其他数据传输命令。这个组合的实际可用性取决于服务端实现：主流 FTP 服务端认这套顺序，但一些老服务端在收到 REST 后只把它标记给下一条 RETR，如果 WinINet 的 FtpOpenFile 和 REST 之间发生了额外交互，偏移就丢了。所以我一般把“服务端是否支持 REST 续传”做成可配置项，不支持的情况下退化为全量重新下载。断点续传的本地侧逻辑不难：打开本地文件时用 FILE_BEGIN 加偏移直接定位到已下载位置，文件打开模式用 OPEN_ALWAYS。上传方向的断点续传更麻烦，需要 APPE 追加写，或者像 3.3 那样干脆用临时文件全量重传——生产上我优先选后者，逻辑简单，坑最少。
5.2 分块大小与超时的再平衡：最后两个参数习惯
4.1 的下载分块用的是 32KB，3.2 的上传分块用的是 8KB，这不是随手写的。上传时数据从本地磁盘到网络，8KB 缓冲在弱网上丢包重传成本低；下载时网络到本地，32KB 能充分利用带宽又不至于让内存压力失控。如果你面对的是一台 1Gbps 的机房内网 FTP，两块都可以往 64KB 调；如果是跨公网传，老老实实回到 8KB 到 16KB。
最后一个习惯：每次写完 FTP 工具，第一步不是测上传下载，而是列目录。只要目录列表能稳定跑出来，说明连接、登录、被动模式、字符集四条链路都是通的；在这四条链路没确认前，传文件传一半断掉是大概率事件，而且你连服务器上到底有什么文件都不知道。我接手的每个 FTP 项目都强制日志里留下服务端状态码和耗时，后面排查不用靠猜，效率高很多。希望帮到你。
本文还有配套的精品资源，点击获取
