我之前在做一个内部管理系统的报表模块时，遇到一个特别基础却让我卡了一整个下午的需求：在SpringBoot项目里读取resource目录下的一个模板Excel文件。文件明明就在项目里躺着，代码用new File()怎么都读不到，不是报路径不存在就是空指针。后来和同事一聊才发现，这个问题不只是新手会碰见，很多写了两三年Java的人也经常在打包部署后踩坑。这篇就结合我当时排查和实测的经过，把SpringBoot中读取resource目录文件的六种方法完整拆开讲一遍，顺便把各自的坑和适用场景也一并交代清楚。

1. 为什么要写这六种方法

1.1 一个看似简单却总出错的场景

先还原一下当时的场景：项目里有一个src/main/resources/templates/目录，下面放着若干JSON模板文件，业务启动时要把这些模板加载进内存，供后续接口动态渲染。本地IDE里跑SpringBoot，一切正常；一旦用Maven打成jar包部署到服务器，程序就报FileNotFoundException。

这事的根源在于：resource目录下的文件在编译期会被打包进jar包内部，它不再是一个操作系统层级上"看得见"的普通文件路径。你在本地用相对路径src/main/resources/xxx.json能读到，是因为IDE把src/main/resources配成了classpath目录；而打包后就完全变了形态。因此读resource文件不能想当然用new File()，必须通过classpath机制来定位。

1.2 六种方法的适用场景对比

我把项目里实际用过的、以及调研过程中确认可行的方案整理成了六种：

一句话总结：读取resource目录文件的本质，不是"找路径"，而是"定位classpath资源"。先懂这个底层逻辑，下面每个方法看起来就会非常顺。

2. 读resource文件的底层原理

2.1 classpath到底是什么

很多新手搞不懂classpath，我习惯用一个生活化类比来解释。你去快递站取件，不需要知道快递车走哪条路、货架在几号区，只需要给取件码；程序找类文件、找配置资源也一样，classpath就是一套统一的"逻辑取件码规则"。Maven项目里，src/main/resources目录下的所有文件最终会被拷贝到target/classes下，和编译后的.class文件站在同一层。运行Java程序时，JVM把target/classes（或jar内的BOOT-INF/classes）作为classpath根目录之一。

所以，当你说"读取classpath:data/template.json"时，程序是在classpath根目录下找data/template.json，而不是在操作系统的绝对路径里找。这个思维转换是解决所有"resource读取失败"问题的第一步。

2.2 三类加载器的本质差异

结合上面的逻辑，可以看三组关键对象：

• ClassLoader：JDK提供的类加载器，负责从classpath中加载类和资源。通过getResourceAsStream可以直接返回资源的输入流。
• Resource和ResourceLoader：Spring在JDK之上封装的一套资源抽象，用classpath:前缀统一描述资源位置。
• File：JDK的文件对象，直接对应文件系统路径，和classpath没有直接关系，这也是new File("classpath:xxx")这种写法错误的原因。

在实际编码中，ClassLoader更底层，Resource更方便，File更适合处理文件系统里的临时产物。三者的选择顺序，取决于你是否需要拿到文件实体，以及你的代码运行在什么环境里。

3. 六种方法的完整代码实现

3.1 方法一：ClassPathResource + InputStream

这是我在SpringBoot项目里最常用的一种。它读取的是classpath:前缀对应的资源，API简洁，并且拿到了Spring的Resource对象后，可以自由地转成InputStream、File或者URL，后续扩展性最好。

import org.springframework.core.io.ClassPathResource; import org.springframework.util.StreamUtils; import java.nio.charset.StandardCharsets; public class ReadResourceDemo1 { public static String readByClassPathResource() { ClassPathResource resource = new ClassPathResource("data/template.json"); try (InputStream inputStream = resource.getInputStream()) { return StreamUtils.copyToString(inputStream, StandardCharsets.UTF_8); } catch (IOException e) { throw new RuntimeException("读取资源失败", e); } } }

这里有三个细节值得注意。第一，ClassPathResource默认以classpath根目录为基准，如果文件在data子目录下，就必须写全路径data/template.json。第二，resource.getInputStream()拿到的是输入流，大多数场景下用流就够了，不需要把资源转成File。第三，流用完必须关闭，我习惯用try-with-resources，省去手动关流的麻烦。

3.2 方法二：ResourceLoader注入读取

ResourceLoader是Spring提供的一个更抽象的接口，它的好处是：你可以通过字符串形式的路径前缀来动态指定资源类型，比如classpath:、file:、url:。在SpringBoot里，直接注入即可，Spring容器会自动装配。

import org.springframework.core.io.Resource; import org.springframework.core.io.ResourceLoader; import org.springframework.stereotype.Component; import org.springframework.util.StreamUtils; @Component public class ReadResourceDemo2 { private final ResourceLoader resourceLoader; public ReadResourceDemo2(ResourceLoader resourceLoader) { this.resourceLoader = resourceLoader; } public String readByResourceLoader() { Resource resource = resourceLoader.getResource("classpath:data/template.json"); try (InputStream inputStream = resource.getInputStream()) { return StreamUtils.copyToString(inputStream, StandardCharsets.UTF_8); } catch (IOException e) { throw new RuntimeException("读取资源失败", e); } } }

这个方法和方法一的本质区别在于：方法一直接new ClassPathResource，硬编码了资源类型；方法二把路径字符串交给ResourceLoader解析，如果你想统一管理配置，或者同一份代码要读取多种来源的资源，用ResourceLoader更灵活。当时项目里我做一个多租户配置模块时，就是靠这个动态前缀能力，既能读模板目录下的文件，也能读外部挂载盘的文件。

3.3 方法三：ClassLoader.getResourceAsStream

如果不依赖Spring，纯JDK环境下也有办法。通过Thread.currentThread().getContextClassLoader()拿到类加载器，直接调getResourceAsStream获取classpath资源的输入流。

import java.nio.charset.StandardCharsets; public class ReadResourceDemo3 { public static String readByClassLoader() { ClassLoader classLoader = Thread.currentThread().getContextClassLoader(); try (InputStream inputStream = classLoader.getResourceAsStream("data/template.json")) { if (inputStream == null) { throw new RuntimeException("资源不存在: data/template.json"); } return new String(inputStream.readAllBytes(), StandardCharsets.UTF_8); } catch (IOException e) { throw new RuntimeException("读取资源失败", e); } } }

这里有个很容易踩的空指针坑：getResourceAsStream如果找不到资源，返回的是null而不是抛异常。所以调用后先判空再使用。另一个细节是，获取ClassLoader的方式不止一种，我推荐用线程上下文类加载器，因为它在SpringBoot这种多类加载器环境下更可靠，能正确加载到Web容器或框架里动态装配的资源。

3.4 方法四：ResourceUtils + File对象

这个方法前后遇到的分歧比较大，因为它在IDE里跑很顺，打包成jar就失效，不少人因此断言它不能用。先说结论：它适合开发阶段调试，或者部署方式是解压目录而非jar包形态。它的本质是把classpath资源通过file:协议转成文件系统上的真实File对象。

import org.springframework.util.ResourceUtils; import java.io.File; import java.io.FileInputStream; import java.nio.charset.StandardCharsets; public class ReadResourceDemo4 { public static void readByResourceUtils() { try { File file = ResourceUtils.getFile("classpath:data/template.json"); String content = new String(new FileInputStream(file).readAllBytes(), StandardCharsets.UTF_8); System.out.println(content); } catch (IOException e) { throw new RuntimeException("读取资源失败", e); } } }

为什么jar包环境下这个方法会失效？因为jar包里的内容不是操作系统的平铺文件，FileInputStream没法直接打开一个位于jar内部的路径。如果你只是本地开发时读取配置文件做测试，这个方法简单直接，完全没问题；如果是打成jar跑生产，就尽量别碰它。

3.5 方法五：Hutool / Commons-IO封装读取

第三方工具类能帮你省掉大量样板代码。Hutool的ResourceUtil一行搞定，Commons-IO配合Guava的Resources也能做到。它们的底层实现和我上面说的方法三大同小异，只是封装了判空、编码处理等细节。

// Hutool import cn.hutool.core.io.resource.ResourceUtil; String content = ResourceUtil.readUtf8Str("data/template.json"); // Commons-IO + Guava import org.apache.commons.io.IOUtils; import com.google.common.io.Resources; import java.nio.charset.StandardCharsets; byte[] bytes = IOUtils.toByteArray(Resources.getResource("data/template.json")); String content = new String(bytes, StandardCharsets.UTF_8);

Hutool的readUtf8Str方便之处在于，读文本时自动处理了UTF-8编码，不需要手动new String(inputStream.readAllBytes(), StandardCharsets.UTF_8)。不过引入这类工具之前要考虑团队规范，如果项目本身已经有Commons-IO，就没必要再加Hutool；如果两个都没有，加一个Hutool确实能提升日常开发效率。

3.6 方法六：ServletContext读取（Web环境）

这个方法我是在做传统Servlet项目时才派上用场的。如果你的SpringBoot应用仍以war包形式部署在外部容器里，ServletContext是Web容器提供的全局上下文对象，可以直接用getResourceAsStream读取classpath下的资源，路径以/WEB-INF/classes/开头。

import javax.servlet.ServletContext; import javax.servlet.http.HttpServletRequest; import java.nio.charset.StandardCharsets; public class ReadResourceDemo6 { public static String readByServletContext(HttpServletRequest request) { ServletContext servletContext = request.getServletContext(); try (InputStream inputStream = servletContext.getResourceAsStream("/WEB-INF/classes/data/template.json")) { if (inputStream == null) { throw new RuntimeException("资源不存在"); } return new String(inputStream.readAllBytes(), StandardCharsets.UTF_8); } catch (IOException e) { throw new RuntimeException("读取资源失败", e); } } }

用这个方法时最需要注意的是环境约束：只有Web应用运行在外置Servlet容器里，ServletContext才可用；SpringBoot默认用内嵌Tomcat以jar方式启动时，虽然也存在ServletContext，但资源路径的解析逻辑和war包不同，直接用这个方式容易吃哑巴亏。现在多数项目都以内嵌容器为主，这个方法出场率不高，了解即可。

4. 实际项目中的问题排查与避坑实录

4.1 打包成jar后ClassPathResource读不到文件

我遇到过一次很典型的问题：代码本地一切正常，部署到测试服务器后抛FileNotFoundException。排查时先在本地执行mvn clean package -DskipTests，然后用jar tf target/xxx.jar查看包结构，发现data/template.json被打到了BOOT-INF/classes/data/template.json。

这是因为SpringBoot的可执行jar内部自带装载器，classpath根目录实际是BOOT-INF/classes。很多人在代码里写死绝对路径，或者用了ClassLoader.getResource()拿到URL后又new File(url.toURI())，都会在jar环境下出问题。正确做法是始终用流的方式读取资源，不要去尝试把jar包内部的资源转成File。如果非得转成File，唯一的方案是将流先拷贝到系统临时目录，再在临时目录生成File对象。

4.2 路径带空格或中文的问题

还有一次，项目在移动端展示PDF，我把模板文件放在了带空格的目录下，比如resource/demo files/template.pdf。开发环境能读，但Linux服务器上某些环节会莫名报路径错误，查下来才发现是空格在URL解码时出了问题。

如果路径里有空格，用ClassPathResource时相对安全，因为Spring内部做了URL解码；而直接用ClassLoader.getResource()返回的URL，再手动URLDecoder时就要格外小心编码格式。经验是：资源文件命名尽量避免中文字符和空格，宁可多建一层目录，也不要给后续埋坑。

4.3 想读目录下的所有文件怎么办

有时候不只是读单个文件，而是要遍历resource/templates目录下所有JSON。如果直接用ClassLoader.getResource("templates")拿URL，再通过File遍历目录，在jar包环境下会非常痛苦，因为目录不存在于文件系统中。

我当时的解决思路有两条。第一，维护一个清单文件：把需要加载的文件名写在一个list.properties里，程序按清单逐个通过ClassPathResource读取，简单可靠。第二，引入可处理嵌套jar的目录扫描工具，比如Hutool的FileUtil.loopFiles不能直接扫jar内部，需要借助JarFile手动遍历jar条目。从成本和稳定性考虑，小规模场景用清单文件最稳。

4.4 编码问题：中文内容读出来乱码

读text、json资源最常见的坑是编码。我见过不少同事用new String(inputStream.readAllBytes())，结果Windows上文件是UTF-8，代码运行在服务器上默认GBK，一读就乱码。这个问题没有技术含量，纯粹是踩坑经验：读取文本资源时，永远显式指定字符集。

// 错误示例，依赖平台默认编码，极易乱码 String content = new String(inputStream.readAllBytes()); // 正确示例 String content = new String(inputStream.readAllBytes(), StandardCharsets.UTF_8);

Hutool的readUtf8Str内部就是固定UTF-8。如果你自己写，一定不要偷懒。这个坑在Windows下开发、Linux下部署的项目里非常常见，属于那种报错不难查、但很耗时间的低级问题。

5. 不同环境下的选择建议

5.1 SpringBoot jar包部署

在这种最常见的方式下，我的选择很固定：优先方法一（ClassPathResource）或方法二（ResourceLoader）。两者都能安全读取jar内部资源，且编码、关闭流这些细节都有Spring帮忙兜底。如果只是简单的工具类调用，方法一更简洁；如果追求可复用性和路径可配置性，方法二更合适。

5.2 本地调试与单元测试

本地调试时，方法四（ResourceUtils+File）阅读起来更直观，因为可以拿到真实的File对象，方便IDE里看路径。但单元测试里我不建议依赖File，因为测试环境同样可能打成jar运行，稳定性会受影响。改用方法三（ClassLoader.getResourceAsStream）写测试最为稳妥。

5.3 嵌入式容器的特殊写法

有朋友问我，既然SpringBoot默认用内嵌Tomcat，是不是也可以用ServletContext。理论上可以，但你没法确定容器何时初始化，也不方便在非Web层调用，所以在绝大多数SpringBoot场景下，直接用ClassPathResource就够用了，没必要绕道ServletContext。

6. 六种方法的对比与我的个人体会

6.1 公开对比表：选型一目了然

6.2 一个六种方法都能跑通的完整示例

如果你想把六种方案放在同一个类里对比验证，可以按下面这个结构组织测试代码。这里我以读取data/template.json为例，统一门面方法输入原始路径。

public interface ResourceReader { String read(); } @Component public class ClasspathReaderFacade { private final ResourceLoader resourceLoader; public ClasspathReaderFacade(ResourceLoader resourceLoader) { this.resourceLoader = resourceLoader; } public String readByClassPathResource() { ClassPathResource resource = new ClassPathResource("data/template.json"); try (InputStream is = resource.getInputStream()) { return StreamUtils.copyToString(is, StandardCharsets.UTF_8); } catch (IOException e) { throw new RuntimeException(e); } } public String readByResourceLoader() { Resource resource = resourceLoader.getResource("classpath:data/template.json"); try (InputStream is = resource.getInputStream()) { return StreamUtils.copyToString(is, StandardCharsets.UTF_8); } catch (IOException e) { throw new RuntimeException(e); } } public String readByClassLoader() throws IOException { try (InputStream is = Thread.currentThread().getContextClassLoader() .getResourceAsStream("data/template.json")) { if (is == null) { return null; } return new String(is.readAllBytes(), StandardCharsets.UTF_8); } } public String readByFileForLocalDebug() throws IOException { File file = ResourceUtils.getFile("classpath:data/template.json"); return new String(new FileInputStream(file).readAllBytes(), StandardCharsets.UTF_8); } public String readByHutool() { return ResourceUtil.readUtf8Str("data/template.json"); } }

运行这个Facade时，建议在IDE里先跑一遍，再mvn clean package后从jar包运行一遍，你就能直观体会到哪些方法在两种环境下都能用，哪些只能本地跑。这个对比经验比单纯背结论更有用。

6.3 我踩过坑之后的几个习惯

第一，代码里固定写ClassPathResource，除非明确需要动态路径才换ResourceLoader，避免在团队里引入乱七八糟的读取风格。第二，所有读取文本的地方强制显式指定UTF-8，不接受默认编码。第三，凡是打包部署后出现资源找不到的报错，第一反应不是改代码，而是先用jar tf查看包内结构，确认文件是否真的在预期位置。第四，遇到列举目录下多个文件的场景，尽早切换到"清单驱动"模式，不依赖目录扫描。这几个习惯帮我省了非常多排查时间，尤其是项目多、环境杂的时候，效果特别明显。

另外，如果你的项目里对配置文件做了profile切换（比如application-prod.yml），读取资源时也要注意资源路径可能随环境变化。我曾经在开发环境用dev/template.json，生产环境用的是prod/template.json，结果因为路径写死导致上线后读了个空。后来统一改成通过配置项传入资源路径前缀，再拼上文件名，问题就彻底没了。

7. 最后再补一句

这类问题的解法本身不复杂，复杂的是很多人不愿意花时间弄懂classpath和文件系统路径的区别，结果换个部署环境就抓瞎。我经历过那个下午的排查后最大的收获，不是记住了六个方法的名字，而是养成了"先确认资源在包里的位置，再决定用哪种方式读"的思考习惯。如果你读完这篇能动手在本地跑一个对比Demo，把jar包打包前后各验证一遍，这类问题以后就很难再坑到你了。