用FTPClient打通浏览器与FTP服务器：目录浏览与文件下载的完整技术代码

1. 浏览器访问 FTP 的真实困境与解决思路浏览器原生只支持ftp://协议做最基础的目录浏览一旦遇到需要账号密码、被动模式、二进制文件下载、跨域触发保存这些场景前端就彻底没辙了。我在做设备固件分发平台时踩过这个坑运维把固件放在内网 FTP 服务器上产品经理要求在网页里点一下就能看到目录、点文件就下载浏览器直接访问ftp://10.0.38.45/mag/要么弹认证框要么直接报错Chrome 新版本甚至已经移除了 FTP 支持。核心矛盾在于浏览器不能直接跟 FTP 服务器对话。FTP 是独立于 HTTP 的协议需要控制连接 数据连接两条通道浏览器沙箱里既没有 socket 权限也拿不到文件流。所以正确路径是让后端用FTPClientApache Commons Net 提供充当翻译官——后端连 FTP 拿目录列表和文件流再通过 HTTP 接口吐给浏览器前端只管渲染和触发下载。这套方案适合谁适合需要在 Web 系统里集成 FTP 文件管理能力的后端和前端开发者尤其是内网设备管理、固件分发、日志归档这类场景。下面我把可复制的FTPClient配置骨架、目录遍历接口、文件流下载接口以及前端触发下载的完整代码拆开讲最后给出验证方法和几个必踩的坑。2. TaoToken 前置把模型能力接进你的 FTP 工具链写这类 FTP 集成代码时我习惯用大模型帮忙生成样板、排查retrieveFileStream返回 null 这类诡异问题。TaoToken 是一个模型调用聚合平台你可以把它理解成一个 Key 调多家模型的入口适合在编码阶段做代码补全、报错分析、接口文档生成。接入前先拿 Key打开 TaoToken API Keys 管理页登录后创建一个 API Key复制保存。这个 Key 就是后续所有模型调用的凭证别硬编码进代码放环境变量里。如果你主要做长期编码和 Agent 类任务可以看 Coding Plan它更适合持续性的代码生成场景只是想临时验证某个模型对 FTP 报错的理解用 模型对话 就够了。接口文档在 接入文档API 基础地址是https://taotoken.net/api注意这个不带 UTM。配置方式跟 OpenAI 兼容接口一致把 base_url 指向 TaoToken 即可。下面这段是环境变量配置避免 Key 泄露# Linux / macOS export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api # Windows PowerShell $env:TAOTOKEN_API_KEYsk-你的key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api注意TaoToken 是模型调用入口不是 FTP 代理也不替代你的编辑器或 FTP 服务器。它只负责在你写代码、查报错时提供模型能力FTP 连接本身还是走你自己的服务器。3. 可复制的 FTPClient 配置骨架先上 Maven 依赖Apache Commons Net 是核心dependency groupIdcommons-net/groupId artifactIdcommons-net/artifactId version3.10.0/version /dependency3.1 连接与登录超时和被动模式必须设原始代码里有两个关键点值得强调setConnectTimeout不设的话账号密码错误会阻塞很久enterLocalPassiveMode不设的话listFiles()和retrieveFileStream()会假死。我把连接逻辑封装成一个可复用的方法import org.apache.commons.net.ftp.*; import java.io.IOException; public class FtpClientFactory { public static FTPClient create(String host, int port, String user, String password) throws IOException { FTPClient ftp new FTPClient(); ftp.setControlEncoding(UTF-8); // 关键1连接超时避免错误配置长时间阻塞 ftp.setConnectTimeout(3000); // 关键2数据连接超时 ftp.setDataTimeout(java.time.Duration.ofSeconds(10)); ftp.connect(host, port); ftp.login(user, password); int reply ftp.getReplyCode(); if (!FTPReply.isPositiveCompletion(reply)) { ftp.disconnect(); throw new IOException(FTP 登录失败replyCode reply); } // 关键3被动模式解决 listFiles/retrieveFile 假死 ftp.enterLocalPassiveMode(); // 关键4二进制传输否则大文件会损坏 ftp.setFileType(FTP.BINARY_FILE_TYPE); return ftp; } }3.2 获取 FTP 根路径pwd 命令的妙用Windows FTP 服务器根路径是/Linux 上可能是/home/mag这种。FTPClient没有直接拿工作目录的 API得用doCommandAsStrings(pwd, )解析public static String getBasePath(FTPClient ftp) throws IOException { String[] rt ftp.doCommandAsStrings(pwd, ); java.util.regex.Pattern p java.util.regex.Pattern.compile(\(.*?)\); java.util.regex.Matcher m p.matcher(rt[0]); if (m.find()) { return m.group(1); } return /; }拿到 basePath 后切换目录要用basePath pathname否则在 Linux 上会跑到系统根目录去。3.3 目录遍历返回给前端的结构化数据后端接口把 FTP 目录转成 JSON 列表前端才能渲染。注意listFiles()返回的FTPFile要区分文件和目录import java.util.*; import java.util.stream.Collectors; public class FtpDirectoryService { public ListMapString, Object listDir(String host, int port, String user, String pwd, String pathname) throws IOException { FTPClient ftp FtpClientFactory.create(host, port, user, pwd); try { String basePath FtpClientFactory.getBasePath(ftp); boolean ok ftp.changeWorkingDirectory(basePath pathname); if (!ok) { throw new IOException(目录不存在: pathname); } FTPFile[] files ftp.listFiles(); ListMapString, Object result new ArrayList(); for (FTPFile f : files) { MapString, Object item new HashMap(); item.put(name, f.getName()); item.put(isDir, f.isDirectory()); item.put(size, f.getSize()); item.put(modified, f.getTimestamp() null ? null : f.getTimestamp().getTimeInMillis()); result.add(item); } return result; } finally { safeClose(ftp); } } private void safeClose(FTPClient ftp) { try { if (ftp.isConnected()) { ftp.logout(); ftp.disconnect(); } } catch (IOException ignored) {} } }3.4 文件流下载retrieveFileStream 的正确收尾retrieveFileStream返回InputStream但有个大坑读完流后必须调用completePendingCommand()否则后续命令会错乱。原始代码里没写这一步实际生产会出问题public void downloadTo(String host, int port, String user, String pwd, String pathname, String fileName, java.io.OutputStream out) throws IOException { FTPClient ftp FtpClientFactory.create(host, port, user, pwd); try { String basePath FtpClientFactory.getBasePath(ftp); ftp.changeWorkingDirectory(basePath pathname); try (java.io.InputStream in ftp.retrieveFileStream(fileName)) { if (in null) { throw new IOException(文件不存在或无法读取: fileName); } byte[] buf new byte[8192]; int n; while ((n in.read(buf)) ! -1) { out.write(buf, 0, n); } } // 关键完成挂起的命令否则连接状态错乱 if (!ftp.completePendingCommand()) { throw new IOException(FTP 传输未正常完成); } } finally { safeClose(ftp); } }4. 浏览器端调用与下载触发后端用 Spring Boot 暴露两个接口前端 fetch 调用即可。4.1 后端 ControllerRestController RequestMapping(/api/ftp) public class FtpController { GetMapping(/list) public ListMapString, Object list(RequestParam String path) throws IOException { return new FtpDirectoryService().listDir( 10.0.38.45, 21, mag, Sugon123, path); } GetMapping(/download) public void download(RequestParam String path, RequestParam String file, HttpServletResponse resp) throws IOException { resp.setContentType(application/octet-stream); resp.setHeader(Content-Disposition, attachment; filename\ java.net.URLEncoder.encode(file, UTF-8) \); new FtpDirectoryService().downloadTo( 10.0.38.45, 21, mag, Sugon123, path, file, resp.getOutputStream()); } }4.2 前端目录浏览与下载async function loadDir(path) { const res await fetch(/api/ftp/list?path${encodeURIComponent(path)}); const items await res.json(); const ul document.getElementById(fileList); ul.innerHTML ; items.forEach(it { const li document.createElement(li); li.textContent it.name (it.isDir ? / : (${it.size} B)); if (it.isDir) { li.onclick () loadDir(path / it.name); } else { li.onclick () { window.location.href /api/ftp/download?path${encodeURIComponent(path)} file${encodeURIComponent(it.name)}; }; } ul.appendChild(li); }); } loadDir(/mag);window.location.href指向下载接口浏览器会自动识别Content-Disposition: attachment并弹出保存框这是最省事的触发方式。如果要做进度条改用fetchReadableStream手动写 Blob。5. 本篇常见错误排查假死无响应listFiles()或retrieveFileStream()卡住不动99% 是没调enterLocalPassiveMode()。主动模式下服务器开随机端口客户端防火墙拦掉就阻塞。下载文件大小不对小文件正常、大文件损坏是没设setFileType(FTP.BINARY_FILE_TYPE)。默认 ASCII 模式会做换行转换二进制文件必坏。retrieveFileStream 返回 null三种可能——文件名大小写不匹配、当前工作目录不对、文件被占用。先listFiles()打印确认文件名再检查changeWorkingDirectory的返回值。Linux 上找不到文件basePath 没拼对。Linux FTP 根是/home/mag这类直接用/会跑到系统根目录。用pwd命令解析出真实 basePath。连接后命令错乱retrieveFileStream读完没调completePendingCommand()下一条命令会读到上一条的响应。中文文件名乱码setControlEncoding(UTF-8)要设且服务器端也要支持 UTF-8。老服务器可能是 GBK需要按实际调整。6. 继续深入的方向目录浏览和文件下载跑通后下一步通常是上传、删除、重命名、断点续传。上传用storeFileStream同样要注意completePendingCommand断点续传用setRestartOffset。这些接口的报错分析、代码生成我一般直接丢给模型处理省得翻文档。如果你在接入过程中遇到 FTP 连接报错、流读取异常这类问题可以到 TaoToken 接入文档 看接口说明或者用 API Keys 配好 Key 后直接在 模型对话 里贴报错让它帮你定位。长期做这类文件服务开发的Coding Plan 会更顺手。最后提醒一句FTP 服务器本身的搭建Linux 用 vsftpdWindows 用 IIS FTP跟客户端代码是两回事Linux 和 Windows 的根路径、权限模型差异很大调试时先确认服务器端配置再排查客户端代码能省一半时间。