本地 IDEA 运行 Spring Boot 项目无法加载 bootstrap.yaml 的问题排查与解决

本地 IDEA 运行 Spring Boot 项目无法加载 bootstrap.yaml 的问题排查与解决

1. 问题背景

在使用 Spring Boot 集成 Nacos 进行配置管理的项目中，bootstrap.yaml 文件非常关键——它包含了 Nacos 的连接信息，在应用启动的早期阶段（bootstrap 阶段）就会被加载。
然而，在本地通过 IDEA 运行项目时，发现程序无法加载 bootstrap.yaml，导致 Nacos 连接失败。

---

2. 问题现象与初步排查

• 现象描述
  在 IDEA 中启动项目，通过 debug 发现 nacos 读取的环境配置信息中并没有加载 bootstrap.yaml 的内容，最终导致连接不到配置中心。

• 初步分析
  经过排查，发现问题并非代码错误，而是pom.xml 中资源文件的配置导致 bootstrap.yaml 被排除。在 Maven 编译过程中，所有资源会被复制到 target/classes/ 目录，而 IDEA 运行时正是从该目录中加载配置文件。如果 bootstrap.yaml 被排除，就无法加载到相应的配置数据。

---

3. pom.xml 中资源配置的详细解析

在项目的 pom.xml 中，通常会有如下资源配置：

<resources>
    <resource>
        <!-- 指定资源文件所在的目录 -->
        <directory>src/main/resources</directory>
        <excludes>
            <exclude>*.yaml</exclude>
            <exclude>*.yml</exclude>
        </excludes>
    </resource>
    <resource>
        <!-- 将本地依赖的 jar 包打包到最终 JAR 中 -->
        <directory>src/main/resources/lib</directory>
        <targetPath>/BOOT-INF/lib/</targetPath>
        <includes>
            <include>**/*.jar</include>
        </includes>
    </resource>
</resources>

3.1 <directory> 标签

• 作用：指定资源文件所在的目录，Maven 会将该目录下的文件复制到 target/classes/ 中。
• 意义：将项目中需要的配置文件、静态资源等打包到最终构建的产物中。

3.2 <excludes> 标签

• 作用：定义一组模式，用于排除不需要复制的文件。例如，<exclude>*.yaml</exclude> 会排除所有 YAML 文件。
• 意义：主要用于实现外部化配置的思想。在生产环境中，通常希望通过外部配置覆盖包内配置，因而排除掉一些环境相关的配置文件。

注意：bootstrap.yaml 是特殊的，它用于在应用启动早期加载 Nacos 的连接信息，不应被排除。如果被排除了，就会导致在本地运行时无法加载相应配置。

3.3 <targetPath> 标签

• 作用：指定资源在最终 JAR 包内的存放路径。
• 示例：将 src/main/resources/lib 中的 jar 文件复制到 JAR 包内的 BOOT-INF/lib/ 目录。
• 意义：Spring Boot 可执行 JAR 包有固定的结构要求，将依赖库放在 BOOT-INF/lib/ 目录中，以便运行时能正确加载。

---

4. 为什么本地运行无法加载 bootstrap.yaml

• IDEA 运行时默认加载的是 target/classes/ 目录中的资源，而非 src/main/resources/ 中的源码文件。
• 如果 pom.xml 中的 <excludes> 配置排除了 application-*.yaml（不小心也可能影响 bootstrap.yaml，如果没有精确配置 include），那么 bootstrap.yaml 就不会复制到 target/classes/，导致启动时找不到 Nacos 连接配置。

---

5. 解决方案

5.1 修改 pom.xml 的资源配置

可以在本地运行的话可以注释掉<exclude>*.yaml</exclude>：

<resources>
    <resource>
        <!-- 指定资源文件所在的目录 -->
        <directory>src/main/resources</directory>
        <excludes>
           <!-- <exclude>*.yaml</exclude> -->
            <exclude>*.yml</exclude>
        </excludes>
    </resource>
    <resource>
        <!-- 将本地依赖的 jar 包打包到最终 JAR 中 -->
        <directory>src/main/resources/lib</directory>
        <targetPath>/BOOT-INF/lib/</targetPath>
        <includes>
            <include>**/*.jar</include>
        </includes>
    </resource>
</resources>

这样做可以确保在本地运行的时候保留 bootstrap.yaml，保证 Nacos 的关键配置信息不会丢失。