Spring Boot Thymeleaf无法访问static下pdf目录的问题求助

排查步骤与解决方案 #

1. 修正Thymeleaf中的资源路径写法

Spring Boot默认将src/main/resources/static下的资源映射到应用根路径（/），因此pdf目录下的文件应通过/pdf/文件名.pdf访问。在Thymeleaf模板中，必须使用**绝对路径（相对于应用根）**而非相对路径，避免因页面URL层级不同导致路径错误：

<!-- 正确写法：使用Thymeleaf的URL表达式 -->
<a href="@{/pdf/test.pdf}" download>下载PDF</a>
<!-- 或者直接写绝对路径 -->
<a href="/pdf/test.pdf" download>下载PDF</a>

如果使用相对路径（如pdf/test.pdf），当页面URL为/user/detail时，实际请求路径会变成/user/pdf/test.pdf，自然返回404。

2. 确认资源已被正确打包

检查项目编译后的target/classes/static目录下是否存在pdf文件夹及对应的PDF文件：

• 执行Maven clean后再compile，确保资源被正确复制到target目录；
• 检查目录名、文件名的大小写（Linux环境下区分大小写，避免部署后出现问题）。

3. 检查是否覆盖了静态资源默认配置

如果项目中自定义了WebMvcConfigurer，确认没有修改静态资源映射路径导致static/pdf未被识别：

// 错误示例：仅指定自定义路径，覆盖了默认配置
@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/custom/**")
                .addResourceLocations("classpath:/custom/");
        // 缺少默认static目录的映射，导致pdf无法访问
    }
}

正确做法是保留默认静态资源映射，或显式添加：

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    // 自定义资源路径
    registry.addResourceHandler("/custom/**")
            .addResourceLocations("classpath:/custom/");
    // 显式保留默认静态资源映射（Spring Boot默认已包含，可选）
    registry.addResourceHandler("/**")
            .addResourceLocations("classpath:/static/", "classpath:/public/", "classpath:/resources/", "classpath:/META-INF/resources/");
}

4. 清除浏览器缓存或重启应用

• 按Ctrl+Shift+R强制刷新页面，避免浏览器缓存旧的404响应；
• 若热部署未同步资源，直接重启Spring Boot应用，确保新添加的pdf目录被加载。

内容的提问来源于stack exchange，提问作者Enzo Lavaud