PAYATHON 2026

Jetty 12.1.9 加载静态资源时报 Illegal char <:> at index 2

数据小许

结论

在 Windows 上,这两个报错对应不同的问题:file://C:/... 的 URI 结构有误;file:///C:/... 是正确的本地盘符 URI 写法,但 Jetty 12.1.9 存在 Windows 子资源路径解析缺陷,解析 index.html 等文件时会触发 Illegal char <:> at index 2。

应先将 Jetty 升级到包含修复的版本,再使用正确的路径配置。Jetty 12.1.10 的发布记录列出了该问题的修复,编号为 #15011。Jetty 12.1.10 发布记录

为什么两种写法都会出错

file://C:/... 改变了 URI 的含义

URI 中,// 后面到下一个 / 之间的部分是 authority。因此,file://C:/some/path/to/html/ 会把 C: 放进 authority,路径部分则是 /some/path/to/html/,无法正确表达预期的本地 C 盘目录。

这里应使用 file:///C:/some/path/to/html/:authority 为空,路径是 /C:/some/path/to/html/。即使目录实际存在,错误的 URI 也不会因此指向预期位置。Java URI 结构说明

Jetty 12.1.9 在解析子资源时错误地使用了 URI 路径

/C:/some/path/to/html/index.html 是 URI 的路径部分。将它直接作为 Windows 文件系统路径解析时,开头多出的 / 使冒号位于索引 2,从而触发异常。

Jetty 的修复说明描述了相同的过程:URI.getPath() 得到 /E:/...,随后传入 Path.resolve(String),导致 Windows 路径解析失败。Jetty 修复 PR #15020

仅把资源创建方式改成 newResource(Path) 仍可能失败:基础目录可以创建成功,但后续的 baseResource.resolve("index.html") 仍会经过有问题的子资源解析逻辑。

如何修改配置

先升级相关 Jetty 依赖,确认运行时加载的版本包含修复。12.1.x 分支的 12.1.10 已包含这项修复;如果使用 BOM 或统一版本配置,也应一并更新,避免 jetty-server 与 jetty-util 混用不同版本。

升级后,可以直接用本地 Path 创建资源。将原代码中创建和配置 ResourceHandler 的部分替换为下面的代码,其他服务器连接和启动代码可以继续使用:

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;

import org.eclipse.jetty.server.handler.ResourceHandler;
import org.eclipse.jetty.util.resource.Resource;
import org.eclipse.jetty.util.resource.ResourceFactory;
import org.eclipse.jetty.util.resource.Resources;

// 放在原 main 方法中。
ResourceHandler handler = new ResourceHandler();
Path baseDir = Path.of("C:/some/path/to/html/").toRealPath();

if (!Files.isDirectory(baseDir) || !Files.isReadable(baseDir)) {
    throw new IllegalStateException(
        "Directory is not readable: " + baseDir);
}

Resource baseResource = ResourceFactory.of(handler).newResource(baseDir);
if (!Resources.isReadableDirectory(baseResource)) {
    throw new IllegalStateException(
        "Resource is not a readable directory: " + baseDir);
}

handler.setBaseResource(baseResource);
handler.setDirAllowed(true);
handler.setWelcomeFiles(List.of("index.html"));

ResourceFactory 提供 newResource(Path) 重载,使用它可以避免手工拼接 URI。Jetty 12.1.9 中,这个重载内部仍会调用 path.toUri(),因此这段配置需要与版本修复配合使用。ResourceFactory API

如果配置来源必须是 URI,也可以保留正确的写法:

URI baseDir = URI.create("file:///C:/some/path/to/html/");
Resource baseResource = ResourceFactory.of(handler).newResource(baseDir);

如何确认问题已经解决

可以在设置 baseResource 前增加一次子资源检查。确认基础目录可读后,再检查 index.html 的解析是否正常:

Resource index = baseResource.resolve("index.html");
if (!index.exists() || index.isDirectory() || !index.isReadable()) {
    throw new IllegalStateException(
        "index.html is not a readable file: " + index.getURI());
}

原代码将 handler 挂载在 /file,端口为 80。启动后,分别访问 http://localhost/file/ 和 http://localhost/file/index.html,检查欢迎页和直接文件访问是否正常。

如果升级后仍出现同样的异常,应先核对运行时实际加载的 jetty-util 版本,并查看完整异常堆栈。基础目录检查通过,并不代表子资源解析也通过。

注意事项

以上本地路径示例假定 Java 进程运行在 Windows 上。如果进程运行在容器或其他操作系统中,需要使用该运行环境能访问的目录。

需要将 file URI 转为 Path 时,应使用 Path.of(uri),避免使用 Path.of(uri.getPath())。前者由文件系统 provider 处理 URI,后者只会把 /C:/... 当作普通路径字符串解析。Java Path API

setDirAllowed(true) 控制目录列表,不能修复路径解析异常。只需要提供文件和欢迎页时,可以将它设为 false。Jetty ResourceHandler 配置说明

备注:内容仅供参考。