Spring Boot Kotlin API中GraphiQL页面空白及React报错问题

核心问题分析 #

你遇到的useSyncExternalStore/useInsertionEffect错误，本质是GraphiQL 4.x版本依赖React 18的新钩子API，但Spring Boot 3.0.x系列的GraphQL Starter默认集成的前端环境不支持这些API。由于Maven依赖传递的自动版本解析逻辑，即使未修改pom.xml，也会自动拉取高版本GraphiQL导致兼容冲突。

可行解决方案 #

1. 强制锁定兼容的GraphiQL版本 #

在pom.xml中添加dependencyManagement节点，锁定graphiql-ui到不依赖React 18的3.x稳定版本，阻断自动升级：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.graphql-java</groupId>
            <artifactId>graphiql-ui</artifactId>
            <version>3.11.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

添加后执行mvn clean install，确保依赖被正确替换。

2. 禁用自动配置，自定义GraphiQL静态资源 #

如果版本锁定无效，可手动引入兼容的静态资源：

• 下载GraphiQL 3.x版本的静态文件（包含index.html、graphiql.min.js等），放入项目src/main/resources/static/graphiql目录
• 在Spring Boot启动类中禁用默认的GraphiQL自动配置：

@SpringBootApplication(exclude = [GraphiQlAutoConfiguration::class])
class YourApplication

fun main(args: Array<String>) {
    runApplication<YourApplication>(*args)
}

• 直接访问/graphiql/index.html即可使用自定义的兼容版本。

3. 匹配Spring Boot与GraphQL Starter版本 #

Spring Boot 3.0.x需对应使用graphql-spring-boot-starter 1.2.x系列版本，避免版本不匹配引发的依赖混乱。在pom.xml中明确指定：

<dependency>
    <groupId>com.graphql-java</groupId>
    <artifactId>graphql-spring-boot-starter</artifactId>
    <version>1.2.0</version>
</dependency>

补充说明 #

• 你之前尝试的清除Maven缓存、重新构建等操作未生效，是因为Maven依赖传递会自动选择最高可用版本，必须通过dependencyManagement强制锁定才能覆盖默认行为
• GraphiQL 4.x的UMD源映射废弃属于正常版本变更，无需关注该警告，核心问题仍为React版本兼容

内容的提问来源于stack exchange，提问作者AlexMrsh