上周帮人看一个内部系统的毛病：C# 客户端要把本地生成的报表文件传到一台 FTP 服务器，代码是很早以前用原生 FtpWebRequest 写的，跑了一年多，换了机房网段之后开始间歇性挂起，日志总是停在一个读取响应的地方，既不报错也不往下走。后来把上传逻辑整个换到 FluentFTP，加上超时、被动模式、二进制模式这几个显式配置，问题就消失了。这件事让我意识到，C# 上传本地文件到 FTP 这件事看起来简单——无非是连上去、丢文件、断开，但真正决定稳定性的全是那些默认值背后的细节。这篇就围绕 FluentFTP 这条线，把连接参数怎么定、本地文件怎么传、大文件怎么控、断点怎么续、出错怎么查，一层一层拆开讲。适合两类人看：一类是刚接手一个 FTP 上传需求、想快速拿到能跑代码的新手；另一类是被原生 API 折磨过、想把上传模块做扎实的老手。文中代码基于 FluentFTP 的异步客户端 AsyncFtpClient，版本差异我会在关键位置标出来，避免你照着抄却编译不过。
1. 选型：为什么在 C# 里上传本地文件，我最后落在 FluentFTP
1.1 原生 FtpWebRequest 的几个硬伤
先把话说清楚，FtpWebRequest 不是不能用，小文件、低频次、内网环境，它完全够。但它有几个绕不过去的结构性毛病，一旦业务量上来就会暴露。
第一个是同步阻塞模型。FtpWebRequest 提供的是 BeginGetResponse / EndGetResponse 的 APM 老式异步，或者干脆同步等着。在 .NET 6 之后，同步等待网络 IO 在高并发场景下会吃掉线程池，几十个上传任务一起排队，线程池饥饿，整个服务卡住。你想改成真正的 async/await，会发现它没有提供 Task 版本，只能自己包一层 Task.Factory.FromAsync，写起来很别扭。
第二个是配置粒度太粗。超时只有一个 Timeout 属性，连接超时和数据读取超时混在一起。传一个 200MB 的文件，你把 Timeout 设成 30 秒，传到一半就断了；设成 10 分钟，网络真断了又要等 10 分钟才发现。这种"一个旋钮管两件事"的设计，在需要精细控制的场景里基本没法用。
第三个是状态处理原始。上传完拿到的只是一个 FtpWebResponse，你要自己判断 StatusCode，自己处理 1xx/2xx/4xx/5xx，自己做重试分类，自己拼接远程路径、自己创建目录、自己判断远程文件是否已存在。这些在业务代码里重复几十遍，最后一定长成一坨谁都不敢动的代码。
注意：FtpWebRequest 在较新的 .NET 版本中已被标记为不建议使用，新项目直接选第三方库是更省事的路。
1.2 FluentFTP 能覆盖的真实场景与它的边界
FluentFTP 是一个纯托管的 FTP/FTPS 客户端库，支持 netstandard2.0 及以上，.NET 6/8 直接引用即可。它把上面那些脏活全包了：异步 API、连接和数据连接分别超时、被动/主动模式自动协商、显式与隐式 TLS、目录递归创建、断点续传、进度回调、上传后校验、自动重连。
我实际用下来，它最值钱的是三块。
一是AutoConnect。它会依次尝试直连、显式 TLS、隐式 TLS，直到握手成功为止。很多内部服务器的加密配置并不统一，有的要求显式 AUTH TLS，有的干脆明文，你不需要为每台服务器写一套配置，AutoConnect 一把梭很省心。
二是上传状态的语义化返回。UploadFile 返回 FtpStatus 枚举，Failed / Success / Skipped 三种，配合 FtpRemoteExists 参数，"远程已存在时覆盖、跳过还是续传"变成一个参数的事，不用自己写判断。
三是进度回调是一等公民。IProgress 里直接给出百分比、已传字节、总字节、瞬时速度、预计剩余时间，做大文件上传进度条不用自己算。
边界也要说清楚。FluentFTP 的客户端实例不是线程安全的，一个实例同一时刻只能干一件事。想做并发上传，必须每个并发槽一个独立实例，这一点后面第 4 章会详细讲。另外它只是客户端，服务器端的行为（比如是否支持 REST 续传命令、是否支持哈希校验命令）它管不了，遇到不支持的服务器你得自己降级处理。
2. 连接层的参数怎么定：超时、模式、编码、加密
2.1 安装与最小可连通验证
安装就一行：
dotnet add package FluentFTP先别急着写业务代码，第一步永远是验证"能不能连上"。我习惯写一个最小验证程序，连上、列出根目录、断开，三步走通再谈上传。
using FluentFTP; // 主机、用户名、密码、端口 var client = new AsyncFtpClient("ftp.example.internal", "user01", "p@ssw0rd", 21); // AutoConnect 会自动尝试 明文 / 显式TLS / 隐式TLS await client.AutoConnect(); if (!client.IsConnected) { throw new InvalidOperationException("连接未建立"); } // 列出根目录，确认账号有权限、编码正常 foreach (var item in await client.GetListing("/")) { Console.WriteLine($"{item.Type} {item.Size,12} {item.Name}"); } await client.Disconnect();这段代码的价值在于它一次性验证了三件事：网络通不通、账号密码对不对、目录列表的中文有没有乱码。如果 GetListing 返回的中文是问号或者一串奇怪符号，说明服务器编码和你客户端的默认编码不一致，直接跳到 2.2 节的编码部分。
提示：生产代码里不要把密码硬编码，也不要把明文密码写进日志。配置走环境变量或密钥管理，日志里打印主机和用户名就够了。
2.2 五个必须显式设置的连接参数
FluentFTP 的默认值偏保守，很多是二十年前的设计，放到今天的网络环境里不一定合适。下面五个参数我基本是必设的，每一个都有明确的理由。
连接超时。默认值偏长。连接超时的含义是"TCP 握手 + 登录认证"这段的时间上限，内网通常 5 秒足够，跨机房给 15 秒。设太长的后果是：服务器挂了，你的任务要干等很久才失败。
client.Config.ConnectTimeout = 15_000; // 毫秒读超时。这是数据通道上两次读取之间的最大间隔，不是整个传输的总时长。这个区别非常关键：传一个 1GB 的文件，总耗时可能是二十分钟，但只要数据一直在流动，读超时就不会触发。所以它可以设得比较短，30 秒足够，用来快速发现"连接还在但服务器不吐数据了"这种假死。
client.Config.ReadTimeout = 30_000; client.Config.DataConnectionReadTimeout = 30_000;数据传输类型。这是踩坑最多的一项，必须设成二进制。
client.Config.UploadDataType = FtpDataType.Binary; client.Config.ListingDataType = FtpDataType.Binary;为什么必须二进制？因为 ASCII 模式会在传输过程中做换行符转换，把本地 CRLF 转成服务器规定的格式，反之亦然。对于纯文本文件这可能无害，但对于 Excel、PDF、图片、压缩包这类二进制文件，一个字节的改动就意味着文件损坏。更隐蔽的是，某些服务器在 ASCII 模式下会把文件末尾的字节当作文本结束符截掉，你上传一个 1024 字节的文件，服务器上只有 1023 字节，校验对不上，还很难查。
编码。服务器上如果有中文、日文、韩文文件名，编码不匹配就会变成乱码，而且往往是"上传成功但文件找不到"——因为文件确实传上去了，只是名字变成了乱码。
client.Config.Encoding = new System.Text.UTF8Encoding(false);UTF-8 是现在的主流，但老服务器可能是 GBK 或者 ISO-8859-1。判断方法是先用 GetListing 看已有的中文文件名显示是否正常，正常就说明当前编码是对的，不正常就换一个试。这一步没有捷径，只能试。
重试次数。FluentFTP 内置了自动重连，网络抖动时它会自己重连再继续。
client.Config.RetryAttempts = 2;这里设成 2 就够了，业务层的整体重试我建议自己控制（见 4.2 节），因为库级别的重连只处理连接层的瞬时故障，处理不了"文件传了一半发现内容不对"这类业务问题。两层重试叠加会放大耗时，出问题时也更难定位。
2.3 主动模式还是被动模式：一次真实的排障
FTP 这个协议比较特殊，它用两条连接：一条控制连接传命令，一条数据连接传文件内容。主动模式（PORT）是服务器主动连客户端，被动模式（PASV）是客户端去连服务器开的一个临时端口。
问题的根源在于：现代网络里，服务器前面几乎一定有防火墙或 NAT，主动模式下服务器去连客户端的高位随机端口，十有八九被挡住。所以现在默认都该用被动模式。
FluentFTP 的默认配置会优先尝试被动，但为了保险，我建议显式指定：
client.Config.DataConnectionType = FtpDataConnectionType.AutoPassive;AutoPassive 的意思是"优先被动，服务器不支持时降级"。如果你们的服务器明确只支持被动，可以直接写 AutoPassive，不用管降级。
踩过的坑是这样：某次换机房之后，上传全部失败，报 425 Can't open data connection。控制连接是通的，登录正常、列目录正常，唯独传文件不行。原因就是新机房的防火墙只放行了 21 端口，被动模式需要的那段高位端口（常见是 50000-51000 或 30000-31000，具体看服务器配置）没有放行。解决办法有两个方向：要么让运维把服务器的被动端口范围固定下来并放开，要么在客户端限定。前者的做法是配置服务器端的 pasv_min_port / pasv_max_port，然后防火墙同步放行这一段；后者比较麻烦，因为端口是服务器分配的，客户端只能被动接受。
注意：如果你发现"连得上、列得出目录、就是传不了文件"，几乎可以百分百确定是数据连接被拦了。别去改代码，先去找负责网络的人确认端口。
3. 上传本地文件的核心实现
3.1 单文件上传的最小闭环与返回值判断
连上之后，上传一个本地文件最短的写法是这样：
var status = await client.UploadFile( localPath: @"D:\data\report_202405.xlsx", remotePath: "/upload/2024/05/report_202405.xlsx", existsMode: FtpRemoteExists.Overwrite, createRemoteDir: true, progress: null, token: CancellationToken.None); if (status != FtpStatus.Success) { throw new IOException($"上传未成功，状态：{status}"); }这里每个参数都值得说一下。
localPath用本地绝对路径。相对路径是从当前工作目录算起的，而 Windows 服务的工作目录经常是 C:\Windows\System32，用相对路径会找不到文件，这是新手最常犯的错误之一。建议进来先 Path.GetFullPath 一下。
remotePath是服务器上的路径，分隔符必须用正斜杠 /。用反斜杠在某些服务器上会被当成文件名的一部分，结果就是在根目录下创建一个叫 "upload\2024\05\report.xlsx" 的怪文件，目录没建成，文件也找不着。
existsMode决定远程同名文件已存在时的行为。Overwrite 是覆盖，Skipped 是跳过，Resume 是续传。第一次跑通建议用 Overwrite，确认链路没问题之后再根据业务需要调整。
createRemoteDir: true是自动创建远程目录，包括中间层级。这个参数救了很多人的命——不设的话，远程目录不存在会直接报 550，而且 550 的报错信息通常只说"找不到文件"，不会告诉你到底是目录不存在还是权限不足，很容易误判。
返回值要考虑 Skipped 的情况。如果你用了 FtpRemoteExists.Skip，远程已存在时返回的是 FtpStatus.Skipped，它既不是失败也不是成功，业务上你可能想把它当作"任务完成"处理，也可能想当作"需要人工确认"。这个语义必须在代码里明确写出来，不然出了数据不一致的问题查起来很费劲。
3.2 远程目录与路径拼装：中文、空格、大小写
路径拼装看着简单，实际上是最容易埋雷的地方。我把常见的几个问题列一下。
中文路径。中文本身没问题，前提是编码设置对了（见 2.2）。但要注意 FTP 服务器对中文目录名的支持程度参差不齐，有的服务器创建中文目录成功，列目录却返回乱码，导致你后续判断"目录是否存在"失败。稳妥的做法是远程目录名统一用英文加数字，中文只出现在最终的文件名里，而且文件名也要做好编码测试。
空格。远程路径带空格是完全合法的，FluentFTP 内部会做转义，你不需要自己加引号。反过来说，如果你手动拼了引号，反而会出错——服务器会把引号当成文件名的一部分。
大小写。Windows 服务器上的 FTP 服务通常不区分大小写，Linux 上的区分。你的代码在测试环境（Windows）跑得好好的，上了生产（Linux）就报文件找不到，多半就是这个原因。建议在代码层面强制远程路径全部小写，或者至少保证拼装逻辑里大小写一致。
路径拼接。不要用字符串加号拼，用 string.Join 或者干脆写一个辅助方法处理首尾斜杠：
static string CombineRemote(string root, params string[] parts) { var segs = new List<string> { root.Trim('/') }; segs.AddRange(parts .Where(p => !string.IsNullOrWhiteSpace(p)) .Select(p => p.Trim('/'))); return "/" + string.Join("/", segs); }这个方法的意图很直接：把每一段的头尾斜杠去掉，中间用单个斜杠连起来，最后补一个开头斜杠。这样无论调用方传的是 "/upload/"、"upload" 还是 "/upload//"，结果都是规范的 "/upload/..."。看起来是小事，但路径拼接出问题的时候，你看到的只是一个 550，很难第一时间联想到多了一个斜杠。
3.3 大文件：分块大小、进度回调与断点续传
先说一个容易误解的点：你不需要自己给文件分块。FluentFTP 内部本来就是按块读写流再发出去的，你只需要调 UploadFile，剩下的交给它。你能控制的是块的大小：
client.Config.TransferChunkSize = 1024 * 1024; // 1MB这个参数的含义是每次读写缓冲区的大小，默认通常在 64KB 左右。为什么要调大？算一下就明白：一条 100Mbps 的链路理论峰值是 12.5MB/s，如果每块 64KB，意味着每秒要做将近 200 次读写加发送，每次都有固定的函数调用和网络栈开销；调成 1MB，每秒只有 12 次左右，固定开销被摊薄，吞吐能明显上去。但不是越大越好，块越大内存占用越高，而且如果单块太大导致某次写超时，重传的代价也更大。1MB 到 4MB 是比较稳的区间，我一般按文件大小分档：小于 10MB 用默认值就行，10MB 到 500MB 用 1MB，500MB 以上用 4MB。
进度回调的用法：
var progress = new Progress<FtpProgress>(p => { // 注意：回调可能在线程池线程上执行 Console.WriteLine($"{p.Progress,6:F1}% {p.TransferredBytes}/{p.TotalBytes} " + $"{p.TransferSpeed / 1024:F0} KB/s 剩余 {p.ETA}"); }); await client.UploadFile( localPath, remotePath, FtpRemoteExists.Overwrite, createRemoteDir: true, progress: progress);FtpProgress 里几个字段的含义要搞清楚：Progress 是 0 到 100 的百分比；TransferredBytes 是本次已传字节；TransferSpeed 是瞬时速度，单位字节每秒；ETA 是预计剩余时间。有个细节要注意，进度回调默认不会每传一个字节就触发一次，它是按块触发的，所以小文件可能只收到 0% 和 100% 两次回调，这是正常的。
在控制台程序或没有 SynchronizationContext 的环境里，Progress 的回调会在 ThreadPool 线程上执行。如果你的回调里要去更新 UI 控件或者操作非线程安全的集合，必须自己切回主线程或者加锁。我见过有人直接在回调里往一个 List 里 Add，然后在主线程遍历，然后偶发地炸了，就是这么来的。
断点续传。用 FtpRemoteExists.Resume：
var status = await client.UploadFile( localPath, remotePath, FtpRemoteExists.Resume, createRemoteDir: true);它的工作原理是：先查远程文件的当前大小，然后从本地的这个偏移量开始继续发。前提是服务器支持 REST 命令（大多数都支持），并且远程那个不完整文件确实是你本地这个文件传了一半的结果。
这里有个必须提醒的风险：如果本地文件在失败后被修改过，续传就会得到一个前半段是旧内容、后半段是新内容的拼接文件，而且大小完全正确，校验大小根本查不出来。所以我的做法是续传前先核对本地文件的最后修改时间和大小是否和上次记录一致，不一致就改成覆盖上传。
3.4 上传后校验：文件大小与哈希
上传返回成功，不代表服务器上那个文件就是完整的。网络层的确认只说明"数据发出去了"，中间经过代理、防火墙、磁盘满、配额限制，都可能让落盘的内容不完整。所以我习惯在上传后做一次校验。
最轻量的校验是对比大小：
var localSize = new FileInfo(localPath).Length; var remoteSize = await client.GetFileSize(remotePath); if (remoteSize != localSize) { throw new IOException($"大小不一致：本地 {localSize}，远程 {remoteSize}"); }这几行代码能拦住绝大多数问题，包括前面提到的 ASCII 模式导致的字节数变化、传输中断导致的截断、磁盘配额不足导致的写入失败。成本几乎为零，强烈建议加上。
更严格的是哈希校验：
var hash = await client.GetChecksum(remotePath, FtpHashAlgorithm.MD5); if (hash != null && hash.IsValid) { Console.WriteLine($"远程 MD5: {hash.Value}"); // 与本地计算出的 MD5 对比 }但要注意，GetChecksum 依赖服务器支持 XMD5、XSHA1 这类扩展命令，很多服务器（尤其是老版本或者精简配置的）并不支持，这时它会返回 null 或者抛出异常。所以哈希校验只能作为增强手段，不能作为唯一手段。工程上我的做法是：大小校验必做，哈希校验包在 try-catch 里，能拿到就比，拿不到就降级，不影响主流程。
4. 批量与并发上传的工程化封装
4.1 配置模型与客户端生命周期
到了批量上传这一步，裸写 client 就不行了，得封装。第一件事是把配置抽出来：
public sealed class FtpUploadOptions { public string Host { get; set; } = ""; public int Port { get; set; } = 21; public string UserName { get; set; } = ""; public string Password { get; set; } = ""; public string RemoteRoot { get; set; } = "/upload"; public int ConnectTimeoutMs { get; set; } = 15_000; public int ReadTimeoutMs { get; set; } = 30_000; public int TransferChunkSize { get; set; } = 1024 * 1024; public int RetryAttempts { get; set; } = 2; public int MaxConcurrency { get; set; } = 3; public bool VerifySize { get; set; } = true; }第二件事是客户端的创建和释放。我应该给一个明确的建议：不要全局单例。原因前面说过，AsyncFtpClient 不是线程安全的，多线程共用一个实例会出现命令乱序、响应错配，表现为莫名其妙的上传失败或者文件内容串了。
合理的生命周期是"每次上传任务一个实例"，或者"每个并发槽一个实例，用完归还"。前者简单，代价是每次都要重新握手登录，一个文件多花几百毫秒；后者效率高，但要自己管池子。对于文件数不多（几百个以内）的场景，前者完全够用，别过度设计。
var client = new AsyncFtpClient(options.Host, options.UserName, options.Password, options.Port); try { client.Config.ConnectTimeout = options.ConnectTimeoutMs; client.Config.ReadTimeout = options.ReadTimeoutMs; client.Config.DataConnectionReadTimeout = options.ReadTimeoutMs; client.Config.DataConnectionType = FtpDataConnectionType.AutoPassive; client.Config.UploadDataType = FtpDataType.Binary; client.Config.ListingDataType = FtpDataType.Binary; client.Config.Encoding = new UTF8Encoding(false); client.Config.TransferChunkSize = options.TransferChunkSize; client.Config.RetryAttempts = options.RetryAttempts; await client.AutoConnect(); // 上传逻辑 } finally { if (client.IsConnected) await client.Disconnect(); client.Dispose(); }finally 里那段不能省。FTP 连接不主动断开，服务器那边会一直挂着这个会话，积累到服务器的最大连接数之后，新的连接全被拒绝，报 421。这个坑很隐蔽，因为本地跑一两次根本看不出来，只有在持续运行的定时任务里才会暴露。
4.2 并发度与重试策略的取舍
并发上传能把总耗时压下来，但不是越多越好。三个限制因素：
服务器的最大并发连接数。很多 FTP 服务默认限制单账号 5 个或 10 个并发，超了直接拒绝。你得先去问清楚或者看配置。
客户端出口带宽。并发到一定程度带宽就吃满了，再加只增加竞争，不增加吞吐。
磁盘 IO。如果本地文件在机械盘上，多个上传线程同时读，磁头来回跳，反而更慢。
我的经验值是 MaxConcurrency 设 3 到 5，先在测试环境跑一轮，观察服务器日志里有没有拒绝连接的记录，再决定要不要往上加。
并发控制用 SemaphoreSlim：
using var gate = new SemaphoreSlim(options.MaxConcurrency); var tasks = files.Select(async file => { await gate.WaitAsync(token); try { await UploadOneAsync(file, options, token); } finally { gate.Release(); } }); await Task.WhenAll(tasks);重试策略要区分错误类型，不能无脑重试。下面这几类属于可以重试：连接超时、读超时、421（服务不可用）、425（数据连接打不开）、426（连接中断）、450/451/452（临时性失败）。这几类通常由网络抖动、服务器瞬时过载引起，隔几秒重试大概率能成。
下面这几类属于不要重试：530（认证失败）、550（权限不足或目录不存在）、553（文件名非法）。这些是配置问题或权限问题，重试一百次结果都一样，只会拖长故障时间、把日志刷满。
static bool IsRetryable(Exception ex) => ex switch { TimeoutException => true, SocketException => true, FtpCommandException fce => fce.CompletionCode is "421" or "425" or "426" or "450" or "451" or "452", _ => false };重试的间隔建议做退避，第一次等 2 秒，第二次等 5 秒，别用固定间隔。固定间隔在服务器过载的场景下会形成"重试风暴"，所有失败任务同一时刻一起重试，把刚缓过来的服务器再打趴下。
4.3 一个可直接抄的 FtpUploader 实现
把前面的东西拼起来，就是这个样子：
public sealed class FtpUploader { private readonly FtpUploadOptions _opt; private readonly ILogger<FtpUploader> _log; public FtpUploader(FtpUploadOptions opt, ILogger<FtpUploader> log) { _opt = opt; _log = log; } public async Task<FtpStatus> UploadAsync( string localPath, string remoteRelativePath, FtpRemoteExists existsMode = FtpRemoteExists.Overwrite, IProgress<FtpProgress>? progress = null, CancellationToken token = default) { var fullLocal = Path.GetFullPath(localPath); if (!File.Exists(fullLocal)) throw new FileNotFoundException("本地文件不存在", fullLocal); var remotePath = CombineRemote(_opt.RemoteRoot, remoteRelativePath); for (var attempt = 1; ; attempt++) { try { using var client = CreateClient(); await client.AutoConnect(token); var status = await client.UploadFile( fullLocal, remotePath, existsMode, createRemoteDir: true, progress: progress, token: token); if (status == FtpStatus.Failed) throw new IOException($"上传失败：{remotePath}"); if (_opt.VerifySize && status == FtpStatus.Success) { var localSize = new FileInfo(fullLocal).Length; var remoteSize = await client.GetFileSize(remotePath, token); if (remoteSize != localSize) throw new IOException( $"大小校验失败：本地 {localSize}，远程 {remoteSize}"); } return status; } catch (OperationCanceledException) { throw; } catch (Exception ex) when (attempt < _opt.RetryAttempts && IsRetryable(ex)) { var delay = TimeSpan.FromSeconds(attempt * 2); _log.LogWarning(ex, "第 {Attempt} 次上传失败，{Delay}s 后重试：{Remote}", attempt, delay.TotalSeconds, remotePath); await Task.Delay(delay, token); } } } private AsyncFtpClient CreateClient() { var c = new AsyncFtpClient(_opt.Host, _opt.UserName, _opt.Password, _opt.Port); c.Config.ConnectTimeout = _opt.ConnectTimeoutMs; c.Config.ReadTimeout = _opt.ReadTimeoutMs; c.Config.DataConnectionReadTimeout = _opt.ReadTimeoutMs; c.Config.DataConnectionType = FtpDataConnectionType.AutoPassive; c.Config.UploadDataType = FtpDataType.Binary; c.Config.ListingDataType = FtpDataType.Binary; c.Config.Encoding = new UTF8Encoding(false); c.Config.TransferChunkSize = _opt.TransferChunkSize; c.Config.RetryAttempts = 1; // 库级重试交给外层统一管 return c; } }这段代码有几个刻意的设计。把库级别的 RetryAttempts 设成 1，是因为重试逻辑统一放到外层循环里，避免两层重试叠加导致一次失败要等很久。校验只在 Success 时做，Skipped 不做校验——远程文件本来就不是这次传的，拿本地大小去比没有意义。OperationCanceledException 单独 catch 并直接抛出，因为它不是故障，是调用方主动取消，重试没有意义。
5. 常见异常排查实录
5.1 认证与权限类
530 Login incorrect。字面意思是账号密码不对，但实际原因往往更复杂。可能是账号被锁定、可能是密码里含有特殊字符被转义了、可能是服务器允许的登录 IP 段不包含你、也可能是账号可以登录但被禁止使用 FTP。排查顺序：先用同账号在命令行 ftp 客户端试，命令行能过说明是代码问题，代码里检查密码有没有被 UrlEncode 之类的东西处理过；命令行也过不了，就去找服务器管理员。
550 Permission denied或 550 后面跟一堆看不懂的话。这两个要分开看。如果发生在创建目录阶段，多半是账号对根目录没有写权限；如果发生在写入文件阶段，可能是目录权限不足，也可能是磁盘配额满了。还有一种特殊情形：某些服务器配置成"目录存在但不允许覆盖"，这时用 Overwrite 就会 550，改成 Resume 或者先删再传才行。
提示：550 是整个 FTP 里最含糊的错误码，它同时表示"文件不存在""权限不足""操作不允许"三种情况。看到 550 别急着改代码，先把远程路径、账号权限、目标目录状态三件事挨个确认一遍。
5.2 数据连接与传输中断类
425 Can't open data connection。数据连接建不起来。按可能性从高到低排：被动端口没放开、服务器被动模式配置的范围和防火墙不一致、客户端出口也被限制了、中间有代理设备改写了控制连接里的 IP 地址（代理不知道内网 IP，导致客户端去连一个连不上的地址）。最后一个情况比较隐蔽，特征是控制连接一切正常，数据连接必然失败，且服务器返回的 PASV 响应里那个 IP 是个内网地址。
426 Connection closed; transfer aborted。传到一半断了。可能是文件太大超过了服务器的超时设置、可能是磁盘满了、可能是服务器主动踢掉了长时间运行的会话。如果是在大文件上传时规律性地出现在某个时间点，基本可以确定是服务器的空闲超时或者会话时长限制。解决办法是开启长连接保活：
client.Config.NoopInterval = 15_000; // 每 15 秒发一个 NOOP 保活 client.Config.SocketKeepAlive = true;421 Service not available。服务器拒绝服务，通常发生在会话数超限、服务器正要重启、或者上一个连接没有正确释放。前面提过，务必在 finally 里 Disconnect，这是预防 421 最有效的手段。如果确认代码里都断了，还是频繁 421，那就去找管理员确认服务器的最大连接数和空闲超时时间。
5.3 编码与文件内容类
中文文件名变乱码。前面 2.2 说过，切换 Config.Encoding。补充一点：不要每次上传都 switch 编码，客户端在连接状态中改编码，后续的命令可能就会出现解析混乱。正确做法是在 Connect 之前把编码定死。
上传成功但文件打不开。第一反应应该是 ASCII/Binary 模式。检查 Config.UploadDataType 是不是 Binary。第二反应是校验大小，如果远程比本地小，那就是被截断了；如果大小一样还是打不开，就得考虑是不是传输途中被某个中间设备改写（比如某些安全设备会对文本类内容做过滤）。
文件大小差若干个字节。典型的换行符转换特征。一个小文本文件如果每行末尾的 CRLF 被转成了一个 LF，文件就会小几行那么多字节。这也是 ASCII 模式的锅，改成 Binary 就好。
5.4 排查速查表与实操心得
把上面的东西整理成一张表，出问题时可以照着对。
| 现象 | 最可能的原因 | 处理方向 |
|---|---|---|
| 530 Login incorrect | 账号密码错、账号锁定、密码含特殊字符 | 先用命令行客户端验证 |
| 421 Service not available | 会话数超限、连接未释放 | 检查 finally 里的 Disconnect |
| 425 Can't open data connection | 被动端口未放开、代理改写 IP | 确认防火墙端口范围，改主动/被动模式 |
| 426 Connection closed | 服务器空闲超时、磁盘满 | 开启 NOOP 保活，检查服务器磁盘 |
| 550 Permission denied | 目录不存在、无写权限、磁盘配额 | 逐项确认路径、权限、配额 |
| 中文名乱码 | 客户端与服务器编码不一致 | 连接前固定 Encoding |
| 文件传完打不开 | ASCII 模式做了换行转换 | 设 UploadDataType 为 Binary |
| 大小差几个字节 | 同上 | 同上，加大小校验 |
| 偶发卡死无响应 | 读超时太长、连接假死 | 缩短 ReadTimeout，开保活 |
| 速度特别慢 | 分块太小、并发太多抢带宽 | 调大 TransferChunkSize，降并发 |
最后分享几个我自己踩出来的经验。
第一，先写验证程序再写业务。任何新的 FTP 服务器接入，我都会先跑一个二十行的验证程序：连上、列目录、传一个 1KB 的二进制小文件、传一个 50MB 的大文件、删掉。这五步能过，后面的业务代码基本不会有环境问题。跳过这一步直接写业务，出问题时你分不清是环境问题还是代码问题，排查时间会翻好几倍。
第二，日志里一定要打远程完整路径和返回码。我见过太多日志只写"上传失败"，连哪个文件、什么错误码都没有，只能靠时间戳去猜。把 remotePath 和 FtpCommandException.CompletionCode 打进去，成本几乎为零，救急的时候价值巨大。
第三，别忽略小文件的性能。传 50MB 大文件你能明显感觉到耗时，但传 2000 个 10KB 的小文件，瓶颈根本不在传输，而在每个文件的命令往返——建连接、登录、检查文件是否存在、发数据、确认、断开。这种情况下最有效的优化是复用连接，一次连接内把 2000 个文件全传完，而不是每个文件建一次连接。如果业务允许，打成一个 zip 传上去再让服务端解压，耗时能降一个数量级。
