用Java实现FTP服务器上传文件，最稳的方案是借助Apache Commons Net库，通过FTPServer或远程FTP服务器完成文件传输，核心步骤包括建立连接、登录、切换目录、上传流和关闭连接。这套方法已经过大量生产环境验证，下面从环境搭建到代码实操，再到高频问题排查,一次讲透。
Java连接FTP服务器的前置准备
引入依赖和确定连接参数
在Java项目中上传文件到FTP服务器，第一步是配置好依赖，以Maven项目为例，在pom.xml中加入：
<dependency>
<groupId>commons-net</groupId>
<artifactId>commons-net</artifactId>
<version>3.9.0</version>
</dependency>
业内专家指出，Commons Net是Java生态里最成熟的FTP客户端库,长期维护且兼容性稳定。
除了依赖，还需要确认FTP服务器的地址、端口（默认21）、用户名、密码，以及目标上传目录是否有写权限，如果你用的是云服务器，还要在安全组里放行21端口（或你自定的端口）。
常见上传方式选择
| 类型 | 适用场景 | 特点 |
|---|---|---|
| 主动模式（Active） | 内网环境 | 服务端回连客户端端口，容易被防火墙拦截 |
| 被动模式（Passive） | 公网/云服务器 | 客户端主动连接服务端数据端口，推荐使用 |
云服务器出于安全考虑，大多禁用主动模式，代码里一定要调用ftpClient.enterLocalPassiveMode()开启被动模式,否则常常出现连接成功但上传卡死的情况。
java ftp上传文件代码示例与关键步骤拆解
完整可运行的上传代码
下面这段代码涵盖从连接到断开的完整流程,可以直接复制修改后使用：
import org.apache.commons.net.ftp.FTP;
import org.apache.commons.net.ftp.FTPClient;
import org.apache.commons.net.ftp.FTPReply;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
public class FtpUploader {
/
上传文件到FTP服务器
@param host 服务器地址
@param port 端口 默认21
@param username 用户名
@param password 密码
@param remotePath 远程目录
@param localFile 本地文件完整路径
/
public static boolean uploadFile(String host, int port, String username,
String password, String remotePath, String localFile) {
FTPClient ftpClient = new FTPClient();
try (InputStream inputStream = new FileInputStream(localFile)) {
// 1.连接服务器
ftpClient.connect(host, port);
int replyCode = ftpClient.getReplyCode();
if (!FTPReply.isPositiveCompletion(replyCode)) {
System.out.println("连接失败，错误码：" + replyCode);
return false;
}
// 2.登录
boolean loginSuccess = ftpClient.login(username, password);
if (!loginSuccess) {
System.out.println("登录失败，请检查用户名密码");
return false;
}
// 3.开启被动模式（重要）
ftpClient.enterLocalPassiveMode();
// 4.设置上传文件类型为二进制，防止图片、压缩包损坏
ftpClient.setFileType(FTP.BINARY_FILE_TYPE);
// 5.切换到远程目录，不存在则创建
if (remotePath != null && !remotePath.isEmpty()) {
if (!ftpClient.changeWorkingDirectory(remotePath)) {
// 逐级创建目录
String[] dirs = remotePath.split("/");
String currentPath = "";
for (String dir : dirs) {
if (dir.isEmpty()) continue;
currentPath += "/" + dir;
if (!ftpClient.changeWorkingDirectory(currentPath)) {
if (!ftpClient.makeDirectory(currentPath)) {
System.out.println("创建目录失败：" + currentPath);
return false;
}
ftpClient.changeWorkingDirectory(currentPath);
}
}
}
}
// 6.获取文件名并上传
String fileName = localFile.substring(localFile.lastIndexOf("/") + 1);
boolean uploadSuccess = ftpClient.storeFile(fileName, inputStream);
if (uploadSuccess) {
System.out.println("文件上传成功：" + fileName);
} else {
System.out.println("文件上传失败，服务端返回：" + ftpClient.getReplyString());
}
return uploadSuccess;
} catch (IOException e) {
e.printStackTrace();
} finally {
try {
if (ftpClient.isConnected()) {
ftpClient.logout();
ftpClient.disconnect();
}
} catch (IOException e) {
e.printStackTrace();
}
}
return false;
}
public static void main(String[] args) {
boolean result = uploadFile("192.168.1.100", 21, "ftpuser", "password",
"/home/ftpuser/uploads", "/tmp/test_file.zip");
System.out.println("上传结果：" + result);
}
}
这段代码处理了几个关键逻辑：连接失败提前退出、目录不存在时自动创建、被动模式切换、二进制传输类型设置。
代码中每一步的作用
FTPReply.isPositiveCompletion()：判断连接是否被服务端接受,避免无效请求。enterLocalPassiveMode()：解决防火墙拦截数据连接的问题。setFileType(FTP.BINARY_FILE_TYPE)：不用二进制传输，图片、压缩包、PDF等文件上传后会损坏。storeFile()：真正的上传动作,返回boolean值表示是否成功。
java ftp上传文件中文文件名乱码和失败问题排查
中文文件名乱码的根源
很多开发者碰到的场景是：文件确实上传上去了，但在FTP服务器上看到的是乱码,原因在于客户端与服务端的字符集不一致。
Windows常用的FTP服务器（如Serv-U）默认可能是GBK，而Linux服务器（如vsftpd）默认是UTF-8,解决办法是在登录后主动指定控制连接编码：
// 在ftpClient.login()之前或之后调用
ftpClient.setControlEncoding("UTF-8");
// 如果服务器是GBK，则改为
ftpClient.setControlEncoding("GBK");
如果改了编码还是乱码，检查服务端配置，以vsftpd为例，在/etc/vsftpd.conf中确认字符集设置：
utf8_filesystem=YES这种问题没有统一的答案，需要结合自己的服务器环境做适配，行业共识认为，统一使用UTF-8是现代系统的首选方案。
上传时卡住不动的排查路径
- 检查是否开启了被动模式，代码里没有
enterLocalPassiveMode()是常见原因。 - 检查本地防火墙是否屏蔽了高端口段,被动模式会随机占用高端口。
- 用同一账号通过FileZilla客户端测试上传,排除账号权限问题。
提升JAVA FTP上传稳定性的进阶策略
连接超时和传输超时设置
默认情况下，FTPClient连接超时时间可能偏长，一旦网络波动，程序会长时间阻塞,建议显式设置合理超时：
ftpClient.setConnectTimeout(5000); // 连接超时5秒 ftpClient.setSoTimeout(30000); // 数据读取超时30秒 ftpClient.setControlKeepAliveTimeout(300); // 控制连接保活
这样设置的好处是，服务器暂时不可达时，程序能在几秒内快速失败,而不是挂死。
使用连接池复用FTP连接
如果业务场景需要频繁上传小文件，每次新建连接开销不小，多数情况下，重复登录、断开是非常耗时的，可以采用对象池复用已有连接，Apache Commons Pool可以配合FTPClient使用：
- 在池中维护若干已登录的FTPClient实例。
- 取出时校验连接是否存活（
sendNoOp()）,失效就重建。 - 归还时重置状态,比如切换回二进制传输模式。
据统计，使用连接池后，多文件上传场景的时间开销能减少一半以上,尤其适合定时批量推送文件的场景。
常见替代技术对比
FTP虽然经典,但某些场景下不一定是唯一选择。
| 技术 | 易用性 | 安全性 | 适用场景 |
|---|---|---|---|
| FTP | 高 | 明文传输，安全性低 | 内网传输、传统业务对接 |
| FTPS（FTP over SSL/TLS） | 中 | 加密传输，安全性高 | 需要加密的FTP场景 |
| SFTP（基于SSH） | 中 | 高强度加密 | 金融、政务等对安全敏感的行业 |
| S3协议 | 高 | HTTPS+签名认证 | 云存储、对象存储服务 |
如果对接的是简米云OSS、酷番云COS等云产品，S3协议更贴合现代架构，性能和数据一致性都优于FTP，不过存量系统要求对接FTP时，掌握Apache Commons Net依然是必修课。
漏传和重传的全量代码逻辑
在批量上传场景中，经常需要实现“失败重试”和“断点续传”,断点续传在FTP中的实现思路是：
- 先检查远程文件大小。
- 本地文件跳过对应的字节数,从断点处继续读流。
- 调用
ftpClient.restartOffset(long offset)告诉服务端从指定偏移量继续存。
ftpClient.restartOffset(remoteFileSize);
这里有一个前提：FTP服务器必须支持REST命令，vsftpd和Serv-U默认支持,部分精简版服务端可能未开启。
一次性全量代码逻辑可以这样设计：
public boolean uploadWithRetry(String localFile, String remoteDir, int maxRetryCount) {
int attempts = 0;
while (attempts < maxRetryCount) {
attempts++;
if (uploadFile(localFile, remoteDir)) {
return true;
}
System.out.println("第" + attempts + "次上传失败，准备重试");
try {
Thread.sleep(2000 attempts);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
}
return false;
}
重试配合指数退避，避免服务器压力过大,是比较务实的做法。
常见问题速查（FAQ）
FTP上传文件时连接失败，怎么定位是网络问题还是服务端问题？
优先检查端口连通性，在命令行执行telnet ftp服务器IP 21，如果端口不通，先排查防火墙和安全组，如果端口通但登录失败，查看服务端日志,很多FTP服务器在配置文件中设置了客户端IP白名单或账号限制。
FTP上传成功后，文件大小为0字节是什么原因？
这个问题的最大嫌疑是传输类型没有设置为二进制，但上传零字节更常见的原因是：本地文件路径错误，导致FileInputStream实际读取到了一个空文件，建议在打开文件流前后打印文件长度,确认文件确实非空且被完整读取。
Java代码里传中文目录路径，一直报550错误怎么办？
550表示“操作失败”，先确认目录是否存在，再用ftpClient.printWorkingDirectory()查看当前所在路径，部分服务器对中文目录名支持不友好，建议上传路径统一使用英文，或者将中文路径转换为URL编码后再拼接，服务端编码不匹配时，changeWorkingDirectory()传入中文很容易被拒绝。
如果只是偶尔传一次文件，直接用上面的单文件上传代码就能满足要求，如果涉及批量、定时或跨服务器同步，建议尽早引入连接池，并考虑是否需要为FTP加上SSL加密或切换到SFTP方案，无论如何，先把Commons Net这套基础打扎实，再考虑后续扩展,是值得的选择。
首发原创文章，作者：王坚，如若转载，请注明出处：https://idctop.com/java%e4%b8%adftp%e6%9c%8d%e5%8a%a1%e5%99%a8%e4%b8%8a%e4%bc%a0%e6%96%87%e4%bb%b6%e6%80%8e%e4%b9%88%e5%86%99ftp%e4%b8%8a%e4%bc%a0%e6%96%87%e4%bb%b6%e5%b8%b8%e8%a7%81%e9%97%ae%e9%a2%98%e6%9c%89%e5%93%aa/
