企业官网建设流程全解析

做 JavaFX 和 SpringBoot 混搭的工程，最怕的不是业务逻辑写不出来，而是项目一启动就卡在控制台那行红字上：No auto configuration classes found in META-INF/spring.factories。这个报错我在自己的工具型客户端项目里踩到过，后来帮朋友远程排查也遇到过好几次，光看这行信息真的劝退，尤其是 SpringBoot 版本升到 3.x 之后，很多人连META-INF/spring.factories这个文件路径都找不到。今天就把这个问题从报错原理到修复步骤完整拆一遍，顺便把 JavaFX 项目里容易踩的 classpath、资源和模块化坑都摆出来。

这个问题的本质，是 SpringBoot 的自动装配入口在启动阶段没有读到任何候选配置类。它可能发生在你新搭工程的第一跑，也可能发生在 SpringBoot 从 2.x 升级到 3.x 之后，甚至可能今天能启动、隔天 clean 一次就崩了。无论哪种场景，排查思路是通用的：先确认依赖在不在，再看版本对应的自动配置文件格式对不对，最后检查运行环境有没有把资源目录漏掉。下面我会按这个顺序来。

1. 先搞清楚这个报错到底在说什么

1.1 报错信息的准确拆解

No auto configuration classes found in META-INF/spring.factories不是一个业务级别的异常，它发生在SpringApplication.run()初始化阶段，由AutoConfigurationImportSelector抛出。这个类做的事情，就是去 classpath 里扫描 SpringBoot 自动配置的候选类集合。扫描不到任何东西，就直接抛异常中断启动。

为什么会抛这个异常？来看 SpringBoot 2.x 的加载逻辑：AutoConfigurationImportSelector.getCandidateConfigurations()通过SpringFactoriesLoader.loadFactoryNames()读取所有 jar 包中的META-INF/spring.factories文件，找出 key 为org.springframework.boot.autoconfigure.EnableAutoConfiguration对应的全部 value 列表。如果这个列表是空的，就抛出：

IllegalStateException: No auto configuration classes found in META-INF/spring.factories. If you are using a custom packaging, make sure that file is correct.

也就是说，这个报错跟你的业务代码基本无关，问题集中在两个环节：要么spring.factories文件根本没出现在运行时 classpath 中，要么出现在 classpath 中了，但文件里没有我们要的那个 key，或者 key 对应的 value 为空、类不存在、格式解析失败。

放到 JavaFX 场景里说就更好理解。你用 JavaFX 写界面，用 SpringBoot 管理服务层对象，启动入口可能是Application.launch()，也可能是SpringApplication.run()。这时候项目结构往往不是 IDEA 默认生成的 SpringBoot 模板，而是手工搭的 Maven/Gradle 工程。只要你漏了依赖、漏了资源文件，或者运行配置里的 classpath 不完整，自动配置加载链就会断在这里。

1.2 自动装配的加载链：一条很容易断的流水线

为了让你后面排查有不慌的底气，这里把整条加载链捋一遍。SpringBoot 启动时有几个关键动作：

1. 创建SpringApplication实例，记录主配置类。
2. 执行run()，进入refreshContext()。
3. 解析配置类时，ConfigurationClassPostProcessor发现主类上有@EnableAutoConfiguration注解（或被@SpringBootApplication包含），于是把任务交给AutoConfigurationImportSelector。
4. AutoConfigurationImportSelector.selectImports()调getCandidateConfigurations()，开始扫描候选自动配置类。
5. SpringFactoriesLoader 把 classpath 下所有 jar 里的META-INF/spring.factories内容读出来，筛选 key 为EnableAutoConfiguration的值。
6. 如果第三步没有返回任何候选类，立刻抛异常。
7. 如果拿到了候选类，Spring 再通过@ConditionalOnClass、@ConditionalOnMissingBean等条件注解逐一过滤，留下真正需要加载的配置类，注册成 Bean。

从第 5 步开始就是最常断的地方。尤其注意 SpringBoot 2.7 到 3.x 这个分水岭：2.7 仍然兼容读取spring.factories，只是会打一个 deprecation 提示；到了 SpringBoot 3.0，官方彻底移除了从spring.factories读取自动配置类的行为，改成了读取META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件。从 3.x 开始，你就算在META-INF/spring.factories里写了EnableAutoConfiguration，Spring 也“假装没看见”。

注意：SpringBoot 3.x 报同一句No auto configuration classes found...时，它找的其实已经换了文件。这时候去改spring.factories是没有用的，必须把自动配置类写进正确的.imports文件里。

2. 为什么会报“没找到自动配置类”：五类现场复盘

2.1spring-boot-autoconfigure没进 classpath，最常见

很多 JavaFX 工程都是手工维护依赖的，pom.xml 里可能只写了：

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

这种情况下一般没事，因为spring-boot-starter会传递依赖spring-boot-autoconfigure。有问题的是那些从旧项目改过来的代码，或者仅引入了spring-boot-core、spring-context这类基础包，根本不存在spring-boot-autoconfigurejar，那自然找不到任何自动配置类。

还有一种情况是直接把 SpringBoot 的 jar 手动拷到一个lib目录，然后通过java -cp lib/* com.xxx.MainKt启动。如果你拷贝的时候漏掉spring-boot-autoconfigure-2.x.jar，或者 IDEA 的 Artifacts 配置里没有把Maven: org.springframework.boot:spring-boot-autoconfigure加进输出，启动就会丢这个异常。

解决思路：先去依赖树里确认真实情况。

mvn dependency:tree -Dincludes=org.springframework.boot:spring-boot-autoconfigure

输出里能看到spring-boot-autoconfigure:jar:2.7.13就说明依赖没问题，接下来查运行配置。如果这里压根没有该 jar，把依赖补上即可。

2.2 版本太高，配置文件路径已经换了

这里特别对应“springboot版本太高”这个痛点。很多朋友从网上找了个 2.x 时代的老项目，本地直接改成了 SpringBoot 3.x，代码一行没动，一启动就报错。原因是很明确的：3.x 不再从spring.factories加载自动配置类，SpringFactoriesLoader 在扫描时找不到默认的自动配置候选，于是抛错，但报错文案还沿用老文本，只改了前半段的提示，这就特别误导人。

我给你整理一个版本对照：

如果你项目里出现了版本混用，比如主工程是 SpringBoot 3.2，但某个第三方 starter 还在提供spring.factories，这个第三方的自动配置就不会被自动加载。要么升级对方 starter，要么自己在主工程里补.imports文件来声明那些你确实需要的自动配置类。

2.3 资源文件被 Maven 过滤掉或根本没打包

JavaFX 项目里很多人会配 Maven 的资源过滤来做配置文件占位符替换，比如在pom.xml里这样写：

<resources> <resource> <directory>src/main/resources</directory> <filtering>true</filtering> </resource> </resources>

filtering=true意味着 Maven 会把 resources 目录里的文本文件当模板处理，替换${...}占位符。这个操作本身没问题，但如果你同时指定了<includes>或者<excludes>，就很容易把spring.factories、spring.handlers、spring.schemas这类文件漏掉。常见配置如下，只保留了**/*.xml：

<resources> <resource> <directory>src/main/resources</directory> <filtering>true</filtering> <includes> <include>**/*.xml</include> </includes> </resource> </resources>

结果就是编译产物target/classes/META-INF/spring.factories根本没生成，或生成了但被过滤成了空文件。Spring 读不到内容，自然报错。

2.4 JavaFX 特有的 classpath 坑

JavaFX 运行方式跟普通 SpringBoot 应用不一样，它通常由javafx.application.Application子类的launch()启动，或者在start()里调SpringApplication.run()。这里有个典型问题：IDEA 新建 JavaFX 模板工程时，默认的 Run Configuration 只是Application类型，不会主动使用 Maven 依赖管理。如果你直接用这个配置运行，classpath 里只有模块自己的target/classes和项目依赖里显式声明的那部分 jar。SpringBoot 的 jar 没被加载，自然找不到自动配置类。

更隐蔽的情况是module-info.java。新版 IDEA 创建 JavaFX 项目默认生成 Java 模块描述文件，模块化部署对 classpath 的约束很严格，SpringBoot 的老式类扫描会受限。JavaFX 模块可能依赖 javafx.controls，但 SpringBoot 的自动装配类在 unnamed module 里，两者互相不能随意访问。多数情况下，JavaFX + SpringBoot 这个组合建议先不搞模块化，把module-info.java删掉，以 classpath 方式运行，能省掉很多脏活。

还有javafx-maven-plugin的javafx:run，这个插件在构建 classpath 时会把编译依赖加入，但要注意 plugin 配置里的<options>，如果你指定了--module-path和--add-modules，Spring Boot 相关 jar 不应放在 module-path 中，否则可能出现类加载顺序问题。

2.5 公共模块里的自动配置类没被带进主程序

多模块工程里，你把一个自定义自动配置类写在 common 模块中，这个自动配置类的作用是给业务模块提供通用 Bean。按理说主程序依赖 common 模块，Spring 就能在 common 的 jar 里找到META-INF/spring.factories。但你实际排查时经常发现：common 模块的target/classes下面没有这个文件，或者有文件但里面是空的。

原因通常是编译顺序带来的资源漏拷。你可以在 common 模块下先手动确认：

ls -la target/classes/META-INF/

如果连META-INF目录都没建，那就是 Maven 配置或目录结构的问题。注意：src/main/resources/META-INF/spring.factories不是src/main/java/META-INF/spring.factories。Java 源码目录下的非.java文件不会自动进入资源输出目录，除非你在 pom 里显式配了<resource>指向src/main/java，比如早期 MyBatis 项目的 Mapper XML 那种配置。一旦你配了<resource>指向 java 目录，还可能把META-INF下不该带的文件也带进去，两边混乱，大概率会出幺蛾子。

3. 完整修复步骤：一套可以照抄的检查清单

3.1 第 1 步：确认 SpringBoot 版本和依赖状态

不管报错多吓人，先跑一次依赖树，确认自动配置的 jar 是不是真的存在。

mvn dependency:tree -Dincludes=org.springframework.boot

重点看版本是否合理。如果版本是 3.x，跳去检查.imports文件；如果版本是 2.x，检查spring.factories。同时确认没有版本冲突，比如项目里同时存在spring-boot-autoconfigure-2.7.13.jar和spring-boot-autoconfigure-3.2.0.jar，某些依赖树冲突会直接让SpringFactoriesLoader读到不同 jar 的META-INF/spring.factories合并结果，这里面只要出现解析错误，也会导致加载失败。

依赖缺失的补救很简单。如果是纯 JavaFX + SpringBoot 客户端，不需要 web 容器，引入最基础的 starter 即可：

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

如果项目非要手工指定spring-boot-autoconfigure，那请连同spring-boot和spring-boot-starter-logging一起引入，别只拉一个 jar，SpringBoot 的日志初始化和上下文刷新在启动早期就会触发，缺了别的 jar 会连环报错。

3.2 第 2 步：找到正确的自动配置文件

运行 SpringBoot 2.x 的项目，确认 jar 内的spring.factories存在，并且包含目标 key：

jar tf ~/.m2/repository/org/springframework/boot/spring-boot-autoconfigure/2.7.13/spring-boot-autoconfigure-2.7.13.jar | grep spring.factories

然后看内容里有没有org.springframework.boot.autoconfigure.EnableAutoConfiguration：

unzip -p ~/.m2/repository/org/springframework/boot/spring-boot-autoconfigure/2.7.13/spring-boot-autoconfigure-2.7.13.jar META-INF/spring.factories

对于 SpringBoot 3.x，文件路径完全不同：

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

查看方式类似，只是文件名变长了。如果这两个文件都不存在，说明spring-boot-autoconfigure这个 jar 本身就有问题，可能是被手工裁剪过，或者仓库里被污染了。建议把本地仓库里的相关目录删除，再重新mvn -U clean package拉取一次。

还有一个容易忽略的点：如果你项目里已经有一个src/main/resources/META-INF/spring.factories，它在编译后会出现在target/classes/META-INF/spring.factories。此时 IDE 和 Maven 它的内容会和所有依赖 jar 里的内容合并。如果这个文件里只有：

org.springframework.boot.autoconfigure.EnableAutoConfiguration=

也就是 key 存在，value 为空，合并后依然可能因为空值导致异常，甚至会把别的 jar 里的自动配置值覆盖掉。这种空 key 文件要优先清理。

3.3 第 3 步：手动补一个 spring.factories 文件做兜底

如果你确实写了自己的自动配置类，比如com.example.javafx.config.JavafxAutoConfiguration，并且项目依然运行在 SpringBoot 2.x，可以在src/main/resources/META-INF/spring.factories里手动声明，文件内容如下：

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\ com.example.javafx.config.JavafxAutoConfiguration

这里需要注意格式细节：

• key 必须是org.springframework.boot.autoconfigure.EnableAutoConfiguration，不要漏掉EnableAutoConfiguration后面的空格和等号。
• value 是自动配置类的全限定类名。
• 如果有多个类，用英文逗号分隔，行尾加\续行。
• 反斜杠后面不能有空格，否则解析会把空格带入类名，导致ClassNotFoundException。
• 类必须真的存在，并且至少标注@Configuration。

自动配置类的基础写法如下：

package com.example.javafx.config; import com.example.javafx.launcher.FxApplicationLauncher; import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Configuration(proxyBeanMethods = false) public class JavafxAutoConfiguration { @Bean @ConditionalOnMissingBean public FxApplicationLauncher fxApplicationLauncher() { return new FxApplicationLauncher(); } }

如果是 SpringBoot 3.x，不写spring.factories，而是新建文件：

src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

文件内容每行一个类全限定名，不需要等号：

com.example.javafx.config.JavafxAutoConfiguration

注意：2.7 也支持读取这个.imports文件，所以如果你希望同一个项目既能跑 2.7 又能平滑升级 3.x，可以直接两个文件都配。旧版读spring.factories时不会因为多了.imports文件而报错，反过来也一样，SpringBoot 3.x 只认.imports。

3.4 第 4 步：修正 Maven 资源过滤和打包配置

首先检查pom.xml里的<resources>，不要写死 include 列表。必须保留资源默认行为，或者明确包含spring.factories和spring/**下的文件：

<resources> <resource> <directory>src/main/resources</directory> <filtering>false</filtering> </resource> </resources>

如果你还需要对某些配置文件做占位符替换，我建议只对特定目录过滤，不要把整个src/main/resources全局过滤。可以这样：

<resources> <resource> <directory>src/main/resources</directory> <filtering>false</filtering> <excludes> <exclude>**/*.yml</exclude> <exclude>**/*.yaml</exclude> <exclude>**/META-INF/**</exclude> </excludes> </resource> <resource> <directory>src/main/resources</directory> <filtering>true</filtering> <includes> <include>**/*.yml</include> <include>**/*.yaml</include> </includes> </resource> </resources>

这样既要避免META-INF下的自动配置文件和 services 文件被过滤，又保留了对application.yml占位符替换的能力。

修改完 pom 后，必须重新执行mvn clean package。因为target/classes里可能残留旧的资源文件，直接package不 clean，坑的是你自己。编译完成后，再去 target 里看一眼：

find target/classes -name "*.imports" -o -name "spring.factories"

确保文件真实存在且内容非空。

3.5 第 5 步：修正 JavaFX 的运行配置和模块化设置

如果你是在 IDEA 里直接右键运行 JavaFX 类报的错，先不要怀疑代码，先看 Run Configuration。

进入Run -> Edit Configurations，找到你的 Application 配置，确认：

1. Use classpath of module选的是正确的主模块。
2. 不要勾选Shorten command line里的JAR manifest，JavaFX 启动器配合该选项很容易出现类加载问题。推荐用none或@argfile（IDEA 2020+ 默认）。
3. 如果你的项目是 Maven 工程，最好先用mvn javafx:run验证一次，如果 Maven 跑得通而 IDEA 跑不通，那就是 IDE 的 classpath 配置问题。

关于module-info.java，我的建议是 JavaFX + SpringBoot 的组合项目去掉模块化。不是不能做，是收益太低，SpringBoot 的自动配置扫描和第三方库兼容在模块化下会遇到太多边界问题。真要模块化，SpringBoot 官方文档都建议使用--add-opens和--add-modules做大量额外配置，对普通工具型客户端来说不值当。

如果项目使用了javafx-maven-plugin，需要检查配置。以下是一个能正常工作的最小配置：

<plugin> <groupId>org.openjfx</groupId> <artifactId>javafx-maven-plugin</artifactId> <version>0.0.8</version> <configuration> <mainClass>com.example.javafx.Launcher</mainClass> </configuration> </plugin>

注意mainClass不能直接指向继承javafx.application.Application的类。这是 JavaFX 的一个老坑：当主类继承Application时，JavaFX 启动器会在main方法之前做一些 native 组件初始化，如果你的main方法里同时调了SpringApplication.run()，就会冲突。推荐的写法是额外写一个不含 JavaFX 组件的启动类，里面调用Application.launch()：

public class Launcher { public static void main(String[] args) { Application.launch(FxApplication.class, args); } }

Spring 容器放进FxApplication.init()或start()中：

public class FxApplication extends Application { private ConfigurableApplicationContext context; @Override public void init() { context = SpringApplication.run(FxApplication.class); } @Override public void start(Stage primaryStage) throws Exception { // 从容器取 Controller / Service } @Override public void stop() throws Exception { context.close(); } }

这种启动方式能让 SpringBoot 的自动装配尽量不受 JavaFX 启动器干扰。很多网上报错都是因为在main方法里强行SpringApplication.run()又直接launch()导致初始化顺序混乱。

4. 排查实录：一个真实的 SpringBoot 3.x 升级案例

4.1 现场症状与初步定位

之前有个工具客户端项目，原本是 SpringBoot 2.4.2 + JavaFX 11，一切正常。后来为了用一个新 SDK，把 SpringBoot 整体升到 3.2.3。升级后一启动，控制台第一行红字就是：

java.lang.IllegalStateException: No auto configuration classes found in META-INF/spring.factories. If you are using a custom packaging, make sure that file is correct.

我看到这个第一反应是：依赖树里 autoconfigure 版本是多少？于是执行：

mvn dependency:tree -Dincludes=org.springframework.boot:spring-boot-autoconfigure

结果输出是：

[INFO] | +- org.springframework.boot:spring-boot-autoconfigure:jar:3.2.3:compile

依赖没问题。再打开 autoconfigure jar 看文件结构：

jar tf ~/.m2/repository/org/springframework/boot/spring-boot-autoconfigure/3.2.3/spring-boot-autoconfigure-3.2.3.jar | grep -E "spring.factories|imports"

结果只有：

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

没有META-INF/spring.factories。这时候我意识到，项目里有个自定义 starter，是几年前在那个工程里自己写的，里面用老方式在src/main/resources/META-INF/spring.factories里声明了一个自动配置类。SpringBoot 升级后，这个 old school 写法彻底失效了，AutoConfigurationImportSelector在 3.x 里连读都不读这个 key，于是报出“找不到自动配置类”。

4.2 从 spring.factories 到 AutoConfiguration.imports

跟朋友确认后，他在自定义 starter 的src/main/resources/META-INF/spring.factories写的是：

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\ com.example.fx.common.config.CommonAutoConfiguration

当时 2.4 时代跑得很稳。升级之后，我在这个 starter 模块里新建了：

src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

内容一行：

com.example.fx.common.config.CommonAutoConfiguration

同时删掉了原先的spring.factories里那行 EnableAutoConfiguration 配置（不删也不报错，但留着容易让人误以为还有效）。

4.3 最终改法

改完重新打包，主工程 clean package 后再启动，依然报错。这次报的就不是 No auto configuration classes found 了，而是ClassNotFoundException: com.example.fx.common.config.CommonAutoConfiguration。

原因也简单：自定义 starter 模块的 jar 没更新到本地仓库，主工程依赖的还是旧的 jar。执行：

mvn -pl common-module install -DskipTests mvn clean package

重新拉依赖后，启动恢复正常。这个案例的关键教训是：改完公共模块，一定要重新 install，而不是只改主工程。JavaFX 项目经常是手工管理多模块，这类“漏 install”问题是排查半天都找不到原因的隐藏杀手。

5. 常见问题速查与避坑心得

5.1 高频问题对照表

5.2 踩过几次坑后总结的几条习惯

第一，资源文件一律不参与 Maven 过滤。SpringBoot 的自动装配机制依赖META-INF下的一堆文本文件，这些文件一旦被占位符替换逻辑污染，轻则启动报错，重则静默加载失败。我现在的习惯是全局filtering=false，只有application.yml这类明确需要环境区分配置的文件才单独开过滤。

第二，做 JavaFX + SpringBoot 客户端，优先选 SpringBoot 2.7.x。这个版本既能读spring.factories，又能读.imports，自定义 starter 的兼容性最好。如果你要用 SpringBoot 3.x，那我建议把项目里自动配置的文件统一改成.imports风格，不要留两份，避免后续维护时被误导。

第三，写自动配置类必须加上条件注解。不要裸写@Configuration就上，最好结合@ConditionalOnClass、@ConditionalOnMissingBean控制生效范围。JavaFX 项目里不同模块可能在不同运行模式下加载，条件不写全，很容易在你换运行方式时冒出各种“Bean 冲突”或“类找不到”的连锁问题。

第四，排查这类启动异常，严格按“依赖 -> 文件 -> 运行配置”的顺序来。不要一上来就去改代码，很多时候代码根本没毛病，就是环境缺了东西。mvn clean package后去target/classes看文件是否存在，这一步能过滤掉 80% 的问题。

第五，如果你遇到的是自定义自动配置类失效，考虑不用自动装配机制，直接在启动类里手动注册也不是不可以的。比如在主启动类上显式加@Import(CommonAutoConfiguration.class)，这算是一个绕开spring.factories/.imports的兜底手段，适合临时救火，但不适合作为长期方案——你以后每加一个自动配置类都要手动 import，很繁琐，也失去了 SpringBoot 约定优于配置的意义。

我在实际项目中最后保留的做法是：JavaFX 客户端用 2.7.x 起步，所有公共模块无论是否需要自动配置，都同时创建spring.factories和AutoConfiguration.imports两个声明文件。前者虽然在新版本中会失效，但对于团队里习惯了老写法的人来说，看文件能知道这里有几个自动配置；后者保证升级到 SpringBoot 3.x 时直接生效。每次改完公共模块，第一件事不是跑主工程，而是install到本地仓库，然后确认target/classes里那份自动配置文件内容是完整的。养成这个习惯后，这个报错基本不会再成为卡住项目启动的门槛。