使用 Spring 发送邮件时异常“Could Not Autowire org.springframework.mail.javamail.JavaMailSender”

2025-06-15

1、简介

本文将带你了解使用 Spring Boot 实现邮件功能时遇到 “Could not autowire org.springframework.mail.javamail.JavaMailSender” 异常的原因以及解决办法。

2、理解异常

首先解释该错误的含义。JavaMailSender 是 Spring 提供的接口，用于抽象邮件发送过程。它继承自 MailSender 接口（提供简单文本邮件的基础功能），特别支持 MIME 消息、附件和 HTML 内容等高级特性。

Spring 的依赖注入机制会自动装配所需 Bean。当遇到 @Autowired 注解或更推荐的构造器注入时，它会从应用上下文（Application Context）中查找匹配的 Bean：

@Service
public class EmailService {

    private final JavaMailSender javaMailSender;

    public EmailService(final JavaMailSender javaMailSender) {
        this.javaMailSender = javaMailSender;
    }
}

当我们注入 Spring 无法找到的 JavaMailSender Bean 并运行应用时，会抛出以下错误：

Field javaMailSender in com.baeldung.email.EmailService required a bean of type 'org.springframework.mail.javamail.JavaMailSender' that could not be found.

或者：

Parameter 0 of constructor in com.baeldung.email.EmailService required a bean of type 'org.springframework.mail.javamail.JavaMailSender' that could not be found.

接下来，我们来分析一下 Spring Boot 无法创建或注入 JavaMailSender Bean 的原因。

3、可能的原因

Spring Boot 通过自动配置简化邮件集成，同时也支持需要定制时的手动 Bean 定义。无论采用哪种方式，应用都必须满足特定条件才能使 JavaMailSender Bean 在应用上下文中可用。

3.1、自动配置

首先，spring-boot-starter-mail 依赖提供了 JavaMailSender 接口的实现。若项目未包含此依赖，Spring 甚至不会尝试配置该 Bean。

其次，若项目包含正确依赖但未完整/正确配置必要的 mail 属性（如 spring.mail.host），Spring Boot 将跳过默认 JavaMailSender Bean 的创建，导致自动装配错误。

最后，若应用显式关闭邮件支持的自动配置（如通过 @EnableAutoConfiguration(exclude = MailSenderAutoConfiguration.class)），Spring 也不会创建该 Bean。

3.2、手动配置

另一种情况是，若需绕过自动配置，可在带有 @Configuration 注解的类中手动定义 JavaMailSender Bean。此方式适用于以下场景：

需处理多个 JavaMailSender。
需要高级定制。
动态邮件服务器配置（无法通过标准 Spring Boot 属性实现）。

此时，若出现以下问题会导致自动装配错误：

包结构不正确。
组件扫描配置错误。

需注意：除非显式定义自定义 JavaMailSender Bean，否则 Spring Boot 会默认启用自动配置。

4、可能的解决方案

在分析解决方案前，先配置项目并添加 spring-boot-starter-mail 依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-mail</artifactId>
    <version>3.2.2</version>
</dependency>

接下来，定义一个简单的 EmailService 类，用于自动配置和手动配置的示例中：

@Service
public class EmailService {

    private static final String NOREPLY_ADDRESS = "noreply@baeldung.com";

    private final JavaMailSender javaMailSender;

    public EmailService(final JavaMailSender javaMailSender) {
        this.javaMailSender = javaMailSender;
    }

    public void sendSimpleEmail(String to, String subject, String text) {

        SimpleMailMessage message = new SimpleMailMessage();
        message.setFrom(NOREPLY_ADDRESS);
        message.setTo(to);
        message.setSubject(subject);
        message.setText(text);

        javaMailSender.send(message);
    }
}

最后，在实现邮件发送功能时，我们有多重可选方案。其中包括配置 Gmail SMTP 服务器，或在本地运行 MailHog 进行功能测试。

4.1、启用自动配置

当存在 Starter 依赖时，Spring Boot 会尝试配置 JavaMailSender，但必须正确定义必要属性。其中 spring.mail.host 是 spring.mail 属性中唯一必须配置的参数。

如下，示例配置指向本地 MailHog 实例：

spring.mail.host=localhost
spring.mail.port=1025
spring.mail.username=
spring.mail.password=

配置 MailHog 属性后，可通过 EmailService 发送简单邮件：

@SpringBootApplication(scanBasePackages = { "com.baeldung.email.service" })
public class EmailSenderApplication implements CommandLineRunner {

    private final EmailService emailService;

    public EmailSenderApplication(EmailService emailService) {
        this.emailService = emailService;
    }

    public static void main(String[] args) {
        SpringApplication.run(EmailSenderApplication.class, args);
    }

    @Override
    public void run(String... args) {
        emailService.sendSimpleEmail(
          "recipient@baeldung.com",
          "Test Subject",
          "Testing the Spring Boot Email!"
        );
    }
}

最后需确保应用未显式禁用自动配置。例如以下配置会阻止 Spring Boot 创建 JavaMailSender Bean：

@SpringBootApplication(exclude = MailSenderAutoConfiguration.class)
public class EmailSenderApplication implements CommandLineRunner { ... }

若未添加此类排除配置，Spring Boot 将自动配置并注册 JavaMailSender Bean。

4.2、手动定义 Bean

另一种方式是手动定义 JavaMailSender Bean，此时需确保该 Bean 被正确添加到 Spring 上下文中。

默认情况下，Spring Boot 会从 main 类所在包开始扫描组件（包含所有子包），识别带有 @Service、@Component、@Configuration 等 Spring 注解的类。

示例如下，再次手动创建指向 MailHog 的 JavaMailSender Bean：

@Configuration
public class EmailConfiguration {

    @Bean
    public JavaMailSender javaMailSender() {
        JavaMailSenderImpl mailSender = new JavaMailSenderImpl();
        mailSender.setHost("localhost");
        mailSender.setPort(1025);

        return mailSender;
    }
}

若该配置类位于应用 main 包之外，除非额外配置组件扫描路径，否则 Spring 无法检测到它：

@SpringBootApplication(
  // 扫描额外的包  
  scanBasePackages = { "com.baeldung.email.config", "com.baeldung.email.service" }
)
public class EmailSenderApplication implements CommandLineRunner { ... }

通过在 scanBasePackages 中指定正确的包路径，可确保 Spring 检测并注册所有所需组件。

5、总结

总之，使用 Spring 发送邮件时遇到 “Could Not Autowire org.springframework.mail.javamail.JavaMailSender” 异常很明显就是 IOC 中缺少 JavaMailSender Bean。

如果是自动配置，则需要检查依赖、配置属性是否正确。如果是手动配置，则需要检查配置类是否被成功扫描到。

Ref:：https://www.baeldung.com/java-mail-sender-bean-missing