Spring Boot 的核心设计之一就是简化配置管理。默认情况下，只需要把键值对写在 application.properties 或 application.yml 中，Spring Boot 就会自动加载并绑定到 Environment 对象里。但当项目需要拆分配置、接入历史遗留属性文件，或者希望从外部路径读取配置时，@PropertySource 注解就派上了用场。它并非 Spring Boot 的专属注解，而是源自 Spring Framework，在 Boot 环境下同样可以工作，只是需要注意一些整合细节。
@PropertySource 的核心作用是指定一个或多个 properties 文件，将其中的键值对添加到 Spring 的 Environment 中。这样，后续无论是通过 @Value 注入，还是通过 Environment 对象读取，都能拿到对应值。在传统 Spring 应用中，这个注解通常配合 @Configuration 类使用；在 Spring Boot 中，同样可以标注在任意配置类或启动类上。不过 Boot 本身已经有一套完整的配置文件发现机制，盲目使用 @PropertySource 反而可能引发值覆盖或者读取不到的问题。因此，理解它的加载时机和资源定位规则十分关键。
基础用法与 Spring Boot 整合方式
先来看一个最简单的示例。假设项目 classpath 下有一个名为 custom-config.properties 的文件，内容如下：
app.name=my-spring-boot-app app.version=2.1.0 app.timeout=5000
接着在任意一个被 Spring 扫描的配置类或者启动类上添加 @PropertySource 注解，指定文件名为 classpath:custom-config.properties。然后就可以使用 @Value 注解注入属性。
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.PropertySource;
@Configuration
@PropertySource("classpath:custom-config.properties")
public class AppConfig {
@Value("${app.name}")
private String appName;
@Value("${app.timeout:3000}")
private int timeout;
public String getAppName() {
return appName;
}
public int getTimeout() {
return timeout;
}
}
这段代码中，@PropertySource 指定了 classpath 下的属性文件，Spring 容器启动时会把文件中的键值对放入 Environment。@Value 中的占位符会被解析，如果键不存在，还可以通过冒号后面的默认值兜底。注意这里 timeout 被定义为 int 类型，Spring 会自动进行类型转换。
Spring Boot 环境下的一个常见误区是：很多人以为 @PropertySource 加载的属性会覆盖 application.properties 中的同名配置，或者反过来以为 application.properties 优先级更高。实际上，在 Spring Boot 中，application.properties 属于默认配置源，它的加载时机比 @PropertySource 更早。默认情况下，@PropertySource 声明的属性源会被添加到 Environment 的属性源列表末尾，这意味着 application.properties 中的同名属性优先级更高，会覆盖 @PropertySource 中的值。如果需要调整优先级，可以通过 @PropertySource 的 factory 属性自定义 PropertySourceFactory 来实现，但这已经超出了基础用法。
与 @ConfigurationProperties 配合实现类型安全绑定
@Value 注入虽然直观，但当属性数量较多或者需要分组管理时，逐个字段注解会显得繁琐。更好的方式是将 @PropertySource 与 @ConfigurationProperties 结合。@ConfigurationProperties 可以把一组前缀相同的属性映射到 Java 对象上，并且支持宽松绑定、JSR-303 校验等特性。不过需要注意，@ConfigurationProperties 默认读取的是 Spring Boot 的主配置文件，它本身并不会直接感知 @PropertySource 加载的属性源，除非在同一个配置类上同时使用两个注解。
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.PropertySource;
@Configuration
@ConfigurationProperties(prefix = "app")
@PropertySource("classpath:custom-config.properties")
public class AppProperties {
private String name;
private String version;
private int timeout;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getVersion() {
return version;
}
public void setVersion(String version) {
this.version = version;
}
public int getTimeout() {
return timeout;
}
public void setTimeout(int timeout) {
this.timeout = timeout;
}
}
在上面的代码中，@ConfigurationProperties 指定前缀 app，这样属性文件中的 app.name、app.version、app.timeout 就会绑定到对应字段。@PropertySource 负责把自定义文件加载到 Environment 中，而 @ConfigurationProperties 在绑定阶段会从 Environment 中读取所有可用的属性源，因此能够拿到这些值。这种方式比单纯使用 @Value 更加结构化，也更适合承载一组业务配置。
还需要强调一点：如果 @ConfigurationProperties 类是通过 @Component 或 @Configuration 注册为 Bean，那么必须确保 Spring Boot 的配置属性绑定功能被启用。Spring Boot 默认会为标注 @ConfigurationProperties 的 Bean 创建绑定代理，但更推荐的做法是在启动类或某个配置类上添加 @EnableConfigurationProperties，并传入对应的配置类。这样可以避免某些扫描顺序导致的绑定失败。
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
@SpringBootApplication
@EnableConfigurationProperties(AppProperties.class)
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
这种方式让配置类与扫描机制解耦，即使 AppProperties 不在组件扫描路径下也能正常工作。当一个模块封装了自己的配置属性时，使用 @EnableConfigurationProperties 是更加明确和可控的选择。
加载多个属性文件与 ignoreResourceNotFound 属性
实际项目中配置往往拆分得很细，比如数据库连接配置、第三方服务配置、消息队列配置等。@PropertySource 支持一次声明多个文件，通过数组形式传入。需要注意的是，如果某个文件实际上并不存在，Spring 启动时就会抛出 FileNotFoundException，导致应用启动失败。这种情况下，可以为该文件设置 ignoreResourceNotFound 属性，让应用在文件缺失时忽略错误，继续启动。
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.PropertySource;
import org.springframework.context.annotation.PropertySources;
@Configuration
@PropertySources({
@PropertySource(value = "classpath:db.properties", ignoreResourceNotFound = false),
@PropertySource(value = "file:${user.dir}/config/third-party.properties", ignoreResourceNotFound = true)
})
public class MultiPropertyConfig {
}
这里使用了 @PropertySources 容器注解来组合多个 @PropertySource。第一个文件 db.properties 必须存在，否则启动失败；第二个文件从文件系统读取，如果不存在则忽略，程序照常启动。这种容错机制在开发环境和生产环境路径不一致时特别有用，可以避免因为某个外部文件缺失导致整个服务不可用。
除了 classpath 和 file 前缀，@PropertySource 还支持从 URL 加载资源，例如 value = "http://config.ippipp.com/app.properties"。不过在生产环境中，通过 URL 加载配置通常不是首选方案，因为网络延迟和可用性无法保证。更稳妥的做法是把外部配置文件放在服务器固定目录，配合 file: 前缀读取，或者使用 Spring Cloud Config 这类集中配置中心。但理解 @PropertySource 的资源定位能力，有助于在轻量级项目中快速落地外部化配置。
自定义 PropertySourceFactory 处理非 properties 格式
@PropertySource 默认只能处理 .properties 和 .xml 格式的属性文件，但实际场景中可能出现 JSON、YAML 甚至加密格式的配置。Spring 提供了 PropertySourceFactory 接口，允许开发者自定义属性源工厂，从任意格式中解析出键值对。Spring Boot 本身对 YAML 有很好的支持，但原生 @PropertySource 无法直接加载 application.yml 以外的自定义 yml 文件。通过实现 PropertySourceFactory，可以扩展 @PropertySource 的能力。
import org.springframework.core.env.PropertySource;
import org.springframework.core.io.support.EncodedResource;
import org.springframework.core.io.support.PropertySourceFactory;
public class YamlPropertySourceFactory implements PropertySourceFactory {
@Override
public PropertySource<?> createPropertySource(String name, EncodedResource resource) throws IOException {
YamlPropertiesFactoryBean factoryBean = new YamlPropertiesFactoryBean();
factoryBean.setResources(resource.getResource());
java.util.Properties properties = factoryBean.getObject();
return new org.springframework.core.env.PropertiesPropertySource(name != null ? name : resource.getResource().getFilename(), properties);
}
}
这段代码借助 YamlPropertiesFactoryBean 将 YAML 文件解析成 Properties 对象，再包装为 PropertySource。使用时，在 @PropertySource 注解上指定 factory 属性即可。
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.PropertySource;
@Configuration
@PropertySource(value = "classpath:custom-config.yml", factory = YamlPropertySourceFactory.class)
public class YamlConfig {
}
自定义 factory 的思路并不限于 YAML，任何可以转换成 Properties 或 Map 的格式都能接入。例如从数据库读取配置、从环境变量中解析 JSON，甚至从远程 API 拉取配置。需要注意的是，自定义 PropertySourceFactory 的 Bean 生命周期不会被 Spring 容器管理，因此在工厂类内部不要依赖注入其他 Bean，保持其无状态和简单性。如果确实需要访问 Spring 上下文，可以考虑在 createPropertySource 方法中使用静态上下文持有者，但这通常不推荐。
还有一点值得注意：Spring Boot 从 2.4 版本开始调整了多文档 YAML 文件的加载行为，默认情况下 application.yml 的多文档支持不会影响自定义的 YAML 属性源。如果自定义 yml 中包含多文档分隔符，使用上述 factory 时需要额外处理，否则只会解析第一段文档。更复杂的场景可以改用 spring.config.import 机制，这也是 Spring Boot 官方推荐的外部配置导入方式。
常见避坑与配置优先级总结
第一个常见问题是属性值注入为 null 或者占位符未解析。出现这种情况，首先要确认 @PropertySource 的文件路径是否正确，以及配置类是否被 Spring 扫描到。其次检查属性键是否完全匹配，因为 properties 文件是精确匹配，不像 @ConfigurationProperties 支持宽松绑定。最后，确认没有在测试类中遗忘加载对应配置，Spring Boot 的单元测试默认不会加载 @PropertySource，需要通过 @TestPropertySource 或 @Import 显式引入。
第二个问题是重复加载导致属性覆盖混乱。同一个文件如果被多个配置类引用，Spring 会创建多个属性源，后加载的会覆盖先加载的。当项目规模变大，配置来源增多时，这种隐式覆盖很难排查。建议集中管理 @PropertySource 声明，比如统一放在一个配置类中，或者通过自定义注解组合使用。对于大型分布式系统，最好引入统一配置中心，而不是让每个服务各自维护大量本地属性文件。
第三个问题涉及配置刷新。@PropertySource 加载的属性在应用启动时一次性读取，运行时修改文件内容不会自动生效。如果需要动态刷新，可以考虑使用 Spring Cloud 的 @RefreshScope，或者自己实现定时重载 PropertySource 并触发 EnvironmentChangeEvent。但这会引入一定的复杂度，不适合在所有场景中开启。
从优先级角度看，Spring Boot 的属性源顺序大致为：命令行参数、Servlet 初始化参数、JNDI、系统属性、操作系统环境变量、application.properties、@PropertySource 声明的属性源、默认属性。实际顺序会因启动方式不同略有变化，但记住 @PropertySource 的优先级低于主配置文件，就能在设计配置体系时避免很多不必要的困惑。如果确实需要让自定义属性覆盖主配置，可以通过自定义 PropertySourceFactory 在创建时调整属性源位置，或者直接使用 spring.config.import 指令导入额外配置，后者在 Spring Boot 2.4 及以上版本中更加灵活可控。
掌握 @PropertySource 在 Spring Boot 中的正确打开方式，能够帮助你在不引入额外框架的情况下，优雅地管理分散的本地属性文件。无论是历史项目迁移、多环境配置拆分，还是第三方依赖的密钥文件读取，这个注解都提供了简洁而可靠的解决方案。只要注意加载顺序、资源定位和类型绑定方式，就能避开大部分配置管理的坑。
Spring Boot@PropertySource外部配置加载修改时间：2026-08-24 12:21:10