Spring Boot使用commons-vfs2访问SFTP路径报相对路径无基础URI错误

该报错核心是Commons VFS 2.4 未能正确识别传入路径为SFTP协议的绝对路径，误认为是无基准URI的相对路径，常见触发原因如下：

• 路径规则理解偏差：你当前拼接的sftp://用户名@主机IP/output中，主机后的单斜杠代表路径是相对于SFTP用户登录后家目录的相对路径，若当前用户家目录下不存在output目录，VFS就会抛出该错误。如果要访问SFTP服务器根目录下的/output绝对路径，需要在主机后加两个斜杠。
• URI解析失败：如果sftp_username或sftp_host变量包含@、/、空格等特殊字符未做转义，会导致VFS无法正确识别SFTP协议头，误将整个字符串判定为本地相对路径。

该问题此前可正常运行大概率是环境变动导致，比如SFTP用户家目录调整、拼接URI的变量值发生变化，原本符合预期的URI变成了非法路径。

方案1：修正路径写法 #

如果要访问SFTP服务器根目录下的output目录，直接将主机后的单斜杠改为双斜杠即可：

FileSystemManager manager = VFS.getManager();
// 双斜杠代表根目录起始的绝对路径
FileObject fileObject = manager.resolveFile("sftp://" + sftp_username + "@" + sftp_host + "//output");
FileObject[] files = fileObject.getChildren();

如果确实要访问用户家目录下的output目录，可以先校验家目录下该路径是否存在。

方案2：使用配置类传递认证信息（更稳定） #

避免直接拼接认证信息到URI引发特殊字符解析问题，推荐通过FileSystemOptions传递SFTP配置：

import org.apache.commons.vfs2.FileSystemOptions;
import org.apache.commons.vfs2.provider.sftp.SftpFileSystemConfigBuilder;

// ...
FileSystemManager manager = VFS.getManager();
FileSystemOptions opts = new FileSystemOptions();
// 关闭主机密钥校验，也可根据需求配置为yes
SftpFileSystemConfigBuilder.getInstance().setStrictHostKeyChecking(opts, "no");
// 配置登录密码，如有密钥认证可替换为对应配置
SftpFileSystemConfigBuilder.getInstance().setPassword(opts, sftp_password);

FileObject fileObject = manager.resolveFile(String.format("sftp://%s//output", sftp_host), opts);
FileObject[] files = fileObject.getChildren();

方案3：显式指定基准目录 #

如果逻辑固定为访问用户家目录下的路径，可以显式指定家目录为基准URI，避免路径识别歧义：

FileSystemManager manager = VFS.getManager();
// 先解析用户家目录作为基准
FileObject baseDir = manager.resolveFile(String.format("sftp://%s@%s/", sftp_username, sftp_host));
// 基于基准目录解析相对路径
FileObject fileObject = manager.resolveFile(baseDir, "output");
FileObject[] files = fileObject.getChildren();

内容的提问来源于stack exchange，提问作者Hikaru Shindo