首页 > 文章 > java教程

Java实现FTP文件上传下载教程

时间：2025-08-12 14:46:48 281浏览收藏

IT行业相对于一般传统行业，发展更新速度更快，一旦停止了学习，很快就会被行业所淘汰。所以我们需要踏踏实实的不断学习，精进自己的技术，尤其是初学者。今天golang学习网给大家整理了《Java实现FTP上传下载功能示例》，聊聊，我们一起来看看吧！

要使用Java实现FTP客户端功能，首选Apache Commons Net库。1. 该库封装了FTP协议的复杂细节，提供connect()、login()、storeFile()、retrieveFile()等直观API，简化开发流程。2. 它支持主动与被动模式切换，自动处理防火墙穿透问题。3. 提供文件上传、下载、目录管理、断点续传等功能。4. 避免手动处理底层Socket通信，显著降低开发难度和维护成本。

如何用Java实现FTP客户端功能 Java上传下载FTP文件示例

用Java实现FTP客户端功能，核心在于利用成熟的第三方库来简化复杂的网络通信细节。在我看来，Apache Commons Net库是完成这项任务的首选，它提供了一套简洁且功能强大的API，可以轻松地连接到FTP服务器、进行用户认证、上传、下载文件，甚至处理目录操作。它的设计考虑到了FTP协议的各种模式（如主动模式和被动模式），大大降低了开发者的心智负担。

解决方案

实现Java FTP客户端功能，主要依赖于Apache Commons Net库中的FTPClient类。以下是一个整合了连接、登录、上传、下载和断开连接的示例代码。这个库真的帮了大忙，不用我们自己去处理TCP/IP套接字那些底层的东西。

import org.apache.commons.net.ftp.FTP;
import org.apache.commons.net.ftp.FTPClient;
import org.apache.commons.net.ftp.FTPFile;
import org.apache.commons.net.ftp.FTPReply;

import java.io.*;

public class FtpClientExample {

    private FTPClient ftpClient;
    private String server;
    private int port;
    private String user;
    private String password;

    public FtpClientExample(String server, int port, String user, String password) {
        this.server = server;
        this.port = port;
        this.user = user;
        this.password = password;
        this.ftpClient = new FTPClient();
        // 设置连接超时时间，这是个好习惯，避免无限等待
        ftpClient.setConnectTimeout(10000); // 10秒超时
    }

    /**
     * 连接并登录FTP服务器
     * @return true if connected and logged in successfully
     * @throws IOException
     */
    public boolean connectAndLogin() throws IOException {
        System.out.println("尝试连接FTP服务器: " + server + ":" + port);
        ftpClient.connect(server, port);
        int replyCode = ftpClient.getReplyCode();
        if (!FTPReply.isPositiveCompletion(replyCode)) {
            System.err.println("FTP连接失败，服务器拒绝连接。错误码: " + replyCode);
            ftpClient.disconnect();
            return false;
        }

        System.out.println("连接成功，尝试登录用户: " + user);
        boolean loggedIn = ftpClient.login(user, password);
        if (!loggedIn) {
            System.err.println("FTP登录失败，用户名或密码错误。");
            ftpClient.disconnect();
            return false;
        }

        // 切换到被动模式，这对于穿透防火墙至关重要
        ftpClient.enterLocalPassiveMode();
        // 设置文件类型为二进制，避免文本文件传输时出现问题
        ftpClient.setFileType(FTP.BINARY_FILE_TYPE);
        System.out.println("登录成功，进入被动模式。");
        return true;
    }

    /**
     * 上传文件到FTP服务器
     * @param localFilePath 本地文件路径
     * @param remoteFileName 远程文件名（包含路径，例如 /path/to/remote_file.txt）
     * @return true if upload successful
     * @throws IOException
     */
    public boolean uploadFile(String localFilePath, String remoteFileName) throws IOException {
        File localFile = new File(localFilePath);
        if (!localFile.exists() || !localFile.isFile()) {
            System.err.println("本地文件不存在或不是文件: " + localFilePath);
            return false;
        }

        InputStream inputStream = null;
        try {
            inputStream = new FileInputStream(localFile);
            System.out.println("开始上传文件: " + localFilePath + " 到 " + remoteFileName);
            boolean success = ftpClient.storeFile(remoteFileName, inputStream);
            if (success) {
                System.out.println("文件上传成功: " + remoteFileName);
            } else {
                System.err.println("文件上传失败，FTP服务器响应: " + ftpClient.getReplyString());
            }
            return success;
        } finally {
            if (inputStream != null) {
                inputStream.close();
            }
        }
    }

    /**
     * 从FTP服务器下载文件
     * @param remoteFilePath 远程文件路径
     * @param localSavePath 本地保存路径（包含文件名）
     * @return true if download successful
     * @throws IOException
     */
    public boolean downloadFile(String remoteFilePath, String localSavePath) throws IOException {
        OutputStream outputStream = null;
        try {
            outputStream = new FileOutputStream(localSavePath);
            System.out.println("开始下载文件: " + remoteFilePath + " 到 " + localSavePath);
            boolean success = ftpClient.retrieveFile(remoteFilePath, outputStream);
            if (success) {
                System.out.println("文件下载成功: " + remoteFilePath);
            } else {
                System.err.println("文件下载失败，FTP服务器响应: " + ftpClient.getReplyString());
            }
            return success;
        } finally {
            if (outputStream != null) {
                outputStream.close();
            }
        }
    }

    /**
     * 列出指定目录下的文件和文件夹
     * @param remotePath 远程目录路径
     * @throws IOException
     */
    public void listFiles(String remotePath) throws IOException {
        System.out.println("列出目录: " + remotePath + " 下的文件和文件夹:");
        FTPFile[] files = ftpClient.listFiles(remotePath);
        if (files != null && files.length > 0) {
            for (FTPFile file : files) {
                String type = file.isDirectory() ? "目录" : (file.isFile() ? "文件" : "未知");
                System.out.println(type + ": " + file.getName() + " (大小: " + file.getSize() + " 字节)");
            }
        } else {
            System.out.println("目录为空或不存在。");
        }
    }

    /**
     * 断开FTP连接
     */
    public void disconnect() {
        if (ftpClient.isConnected()) {
            try {
                ftpClient.logout();
                ftpClient.disconnect();
                System.out.println("FTP连接已断开。");
            } catch (IOException e) {
                System.err.println("断开FTP连接时发生错误: " + e.getMessage());
            }
        }
    }

    public static void main(String[] args) {
        // 请替换为你的FTP服务器信息
        String server = "your_ftp_server_ip_or_hostname";
        int port = 21; // 默认FTP端口
        String user = "your_username";
        String password = "your_password";

        // 本地文件路径和远程文件路径
        String localUploadFilePath = "D:/test_upload.txt"; // 确保此文件存在
        String remoteUploadFileName = "/remote_dir/uploaded_file.txt"; // 服务器上的目标路径和文件名

        String remoteDownloadFilePath = "/remote_dir/file_to_download.zip"; // 服务器上要下载的文件
        String localDownloadSavePath = "D:/downloaded_file.zip"; // 下载到本地的路径和文件名

        FtpClientExample client = new FtpClientExample(server, port, user, password);

        try {
            if (client.connectAndLogin()) {
                // 1. 上传文件示例
                // client.uploadFile(localUploadFilePath, remoteUploadFileName);

                // 2. 下载文件示例
                // client.downloadFile(remoteDownloadFilePath, localDownloadSavePath);

                // 3. 列出文件示例
                // client.listFiles("/"); // 列出根目录
                // client.listFiles("/remote_dir"); // 列出指定目录

            }
        } catch (IOException e) {
            System.err.println("FTP操作中发生IO错误: " + e.getMessage());
            e.printStackTrace();
        } finally {
            client.disconnect();
        }
    }
}

注意： 运行上述代码前，请确保你的项目中已添加Apache Commons Net的依赖。如果你使用Maven，可以在pom.xml中添加：


    commons-net
    commons-net
    3.9.0

如果使用Gradle：

implementation 'commons-net:commons-net:3.9.0' // 检查最新版本

为什么选择Apache Commons Net库？它有哪些核心优势？

在Java中实现FTP客户端，我们有很多选择，但Apache Commons Net库在我看来是那个“久经沙场”的老兵。我记得刚开始接触网络编程时，尝试过直接用Java的Socket API去实现FTP，那真是个噩梦。FTP协议的状态管理、数据连接的建立、主动/被动模式的切换，每一步都充满了细节和坑。直到我发现了Commons Net，感觉就像是找到了救星。

它的核心优势非常明显：

成熟与稳定： 这个库已经存在并维护了很长时间，这意味着它经过了大量实际项目的检验，各种边缘情况和兼容性问题都得到了很好的处理。你不太可能遇到一些奇怪的、未知的协议实现问题。
易用性： 它把复杂的FTP协议细节封装得非常好，你只需要调用connect()、login()、storeFile()、retrieveFile()这些直观的方法，就能完成大部分操作。不需要深入理解FTP命令（如PORT、PASV、STOR、RETR）的底层交互。
功能全面： 不仅仅是上传下载，它还支持文件列表、目录创建/删除、重命名、权限修改等几乎所有FTP协议提供的功能。这对于构建一个完整的FTP管理工具来说非常方便。
模式支持： 自动处理FTP的主动（Active）和被动（Passive）模式切换。尤其是在被动模式下，它能很好地处理数据连接的建立，这对于穿越防火墙至关重要。我实际开发中发现，很多时候连接不上FTP，就是因为没有正确设置被动模式。
活跃的社区和文档： 遇到问题时，很容易在网上找到解决方案和示例代码。这对于开发者来说，无疑是巨大的帮助。

所以，与其自己去“造轮子”，承担巨大的调试和维护成本，不如直接站在巨人的肩膀上，用Commons Net来高效地完成任务。

FTP连接中常见的问题与陷阱有哪些？如何避免？

FTP连接，尤其是在跨网络、有防火墙的环境下，确实会遇到不少“坑”。我个人就踩过好几次，每次都得花时间排查。理解这些常见问题并知道如何规避，能省下不少头发。

被动模式（Passive Mode）的缺失： 这是最常见的问题。FTP协议有两种数据传输模式：主动模式（Active）和被动模式（Passive）。
- 主动模式： 客户端告诉服务器一个端口，服务器主动连接客户端的这个端口来传输数据。这在客户端有防火墙时通常会被阻断。
- 被动模式： 客户端请求服务器打开一个随机端口，并告诉客户端这个端口号，然后客户端连接服务器的这个端口来传输数据。这更适合有防火墙的客户端。
- 避免方法： 几乎在所有情况下，都应该使用被动模式。在FTPClient中，调用ftpClient.enterLocalPassiveMode(); 是强制性的，尤其当你的客户端位于NAT或防火墙后面时。
文件传输类型错误（ASCII vs. Binary）： FTP支持两种文件传输类型：
- ASCII模式： 适用于文本文件，它会根据操作系统自动转换行结束符（如CRLF到LF）。
- Binary模式： 适用于所有非文本文件（如图片、视频、压缩包等），按字节原样传输。
- 陷阱： 如果你用ASCII模式传输二进制文件，文件内容可能会损坏；反之，如果用Binary模式传输文本文件，在某些系统上行尾可能显示不正确。
- 避免方法： 对于所有非文本文件，务必设置ftpClient.setFileType(FTP.BINARY_FILE_TYPE);。对于文本文件，可以考虑ftpClient.setFileType(FTP.ASCII_FILE_TYPE);，但为了通用性，我个人倾向于对所有文件都使用二进制模式，然后在应用程序层面处理文本文件的行结束符问题。
连接超时与断开： 网络不稳定或服务器响应慢可能导致连接超时。如果程序异常退出，FTP连接可能没有正确关闭，导致服务器端残留会话，影响后续连接。
- 避免方法：
  - 设置连接超时：ftpClient.setConnectTimeout(timeoutMillis);。
  - 设置数据传输超时：ftpClient.setDataTimeout(timeoutMillis);。
  - 使用try-catch-finally块确保在任何情况下都能调用ftpClient.disconnect();来关闭连接。这是非常重要的，否则可能导致资源泄露或服务器端会话堆积。
字符编码问题： FTP服务器的文件名或目录名可能使用不同的字符编码（如UTF-8或GBK），如果客户端不匹配，会导致乱码或找不到文件。
- 避免方法： 在连接前设置编码：ftpClient.setControlEncoding("UTF-8");。大多数现代FTP服务器都支持UTF-8。如果遇到乱码，可能需要尝试其他编码。
服务器端权限问题： 即使成功登录，如果用户没有足够的权限在指定目录下创建、修改或删除文件，操作也会失败。
- 避免方法： 检查FTP服务器上为该用户设置的权限。客户端代码通常只能报告权限不足的错误，而不能解决它。

理解并预先处理这些常见问题，能让你的Java FTP客户端更加健壮和可靠。

如何在Java FTP客户端中实现文件列表、目录操作和断点续传？

除了基本的上传下载，一个实用的FTP客户端还需要处理文件和目录的管理，以及更高级的断点续传功能。Apache Commons Net在这些方面也提供了很好的支持。

1. 文件列表（Listing Files）：

列出远程目录下的文件和子目录是常见的需求。FTPClient提供了listFiles()方法来完成这个任务。它返回一个FTPFile对象的数组，每个对象都包含了文件或目录的详细信息。

import org.apache.commons.net.ftp.FTPFile;
// ... (其他导入和类定义)

public void listDirectoryContents(String remotePath) throws IOException {
    System.out.println("列出目录: " + remotePath + " 下的内容:");
    ftpClient.changeWorkingDirectory(remotePath); // 先切换到目标目录，这样listFiles()可以不带路径参数
    FTPFile[] files = ftpClient.listFiles(); // 列出当前工作目录下的所有文件和目录

    if (files != null && files.length > 0) {
        for (FTPFile file : files) {
            String type = "";
            if (file.isDirectory()) {
                type = "目录";
            } else if (file.isFile()) {
                type = "文件";
            } else if (file.isSymbolicLink()) {
                type = "链接";
            } else {
                type = "未知";
            }
            System.out.printf("%-8s %-20s %-10d %s\n", type, file.getName(), file.getSize(), file.getTimestamp().getTime());
        }
    } else {
        System.out.println("目录为空或不存在。");
    }
    // 切换回根目录或者你认为合适的目录，避免后续操作出错
    // ftpClient.changeWorkingDirectory("/");
}

FTPFile对象提供了getName()、isDirectory()、isFile()、getSize()、getTimestamp()等方法，可以获取文件的名称、类型、大小和修改时间等信息。

2. 目录操作：

创建、删除和切换目录也是FTP客户端的基本功能。

创建目录： ftpClient.makeDirectory(directoryPath);
删除目录： ftpClient.removeDirectory(directoryPath); (注意：通常只能删除空目录)
切换工作目录： ftpClient.changeWorkingDirectory(directoryPath); (这会改变当前会话的“当前目录”，影响后续相对路径的操作)
获取当前工作目录： ftpClient.printWorkingDirectory();

示例：

public void manageDirectories() throws IOException {
    String newDir = "/test_new_dir";
    System.out.println("尝试创建目录: " + newDir);
    if (ftpClient.makeDirectory(newDir)) {
        System.out.println("目录创建成功: " + newDir);
        System.out.println("当前工作目录: " + ftpClient.printWorkingDirectory());
        if (ftpClient.changeWorkingDirectory(newDir)) {
            System.out.println("已切换到新目录: " + ftpClient.printWorkingDirectory());
            // 在新目录里做一些操作...
            // 比如上传一个文件到新目录
            // uploadFile("D:/local_file.txt", "new_file_in_new_dir.txt");

            // 切换回父目录
            if (ftpClient.changeToParentDirectory()) {
                System.out.println("已切换到父目录: " + ftpClient.printWorkingDirectory());
            }
        }
        // System.out.println("尝试删除目录: " + newDir);
        // if (ftpClient.removeDirectory(newDir)) { // 只能删除空目录
        //     System.out.println("目录删除成功: " + newDir);
        // } else {
        //     System.err.println("目录删除失败: " + ftpClient.getReplyString());
        // }
    } else {
        System.err.println("目录创建失败: " + ftpClient.getReplyString());
    }
}

3. 断点续传（Resume Transfer）：

断点续传是一个更高级的功能，尤其对于大文件传输非常有用。它的基本原理是：如果传输中断，下次连接时可以从上次中断的位置继续传输，而不是从头开始。

下载断点续传：

检查本地文件是否存在，并获取其当前大小。
告诉FTP服务器从哪个字节偏移量开始传输。
将下载的数据追加到本地文件的末尾。

FTPClient提供了setRestartOffset(long offset)方法来实现这个功能。

public boolean downloadFileWithResume(String remoteFilePath, String localSavePath) throws IOException {
    File localFile = new File(localSavePath);
    long existingFileSize = 0;
    if (localFile.exists() && localFile.isFile()) {
        existingFileSize = localFile.length();
        System.out.println("本地文件已存在，大小: " + existingFileSize + " 字节。尝试断点续传。");
    }

    OutputStream outputStream = null;
    try {
        outputStream = new FileOutputStream(localFile, true); // true表示追加模式
        ftpClient.setRestartOffset(existingFileSize); // 设置从该偏移量开始下载

        System.out.println("开始从FTP下载文件 (续传): " + remoteFilePath + " 到 " + localSavePath);
        boolean success = ftpClient.retrieveFile(remoteFilePath, outputStream);
        if (success) {
            System.out.println("文件下载成功 (续传完成): " + remoteFilePath);
        } else {
            System.err.println("文件下载失败 (续传失败)，FTP服务器响应: " + ftpClient.getReplyString());
        }
        return success;
    } finally {
        if (outputStream != null) {
            outputStream.close();
        }
        ftpClient.setRestartOffset(0); // 重置偏移量，避免影响后续操作
    }
}

上传断点续传： 上传的断点续传通常通过appendFile()方法实现，它会将数据追加到服务器上的现有文件末尾。这要求服务器支持APPE命令。

public boolean uploadFileWithResume(String localFilePath, String remoteFileName) throws IOException {
    File localFile = new File(localFilePath);
    if (!localFile.exists() || !localFile.isFile()) {
        System.err.println("本地文件不存在或不是文件: " + localFilePath);
        return false;
    }

    // 获取服务器上文件当前大小，以便从本地文件的对应位置开始读取
    long remoteFileSize = 0;
    try {
        FTPFile[] files = ftpClient.listFiles(remoteFileName);
        if (files != null && files.length > 0) {
            remoteFileSize = files[0].getSize();
            System.out.println("远程文件已存在，大小: " + remoteFileSize + " 字节。尝试断点续传

好了，本文到此结束，带大家了解了《Java实现FTP文件上传下载教程》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！

文件上传文件下载断点续传 ApacheCommonsNet JavaFTP