从Grails 3升级至Grails 4时应用启动失败，找不到UrlMappings类型Bean

报错核心解析 #

日志显示 UrlMappingsErrorPageCustomizer 组件需要注入 grails.web.mapping.UrlMappings 类型的 Bean，但容器中没有找到匹配的实例。该问题是 Grails 3 到 Grails 4 迁移过程中的高频问题，根因基本都和类扫描、依赖配置、版本兼容相关。

可操作排查步骤 #

• 检查 UrlMappings 类的存放路径
  Grails 4 仅对 grails-app/controllers 路径下的类开启制品自动扫描，迁移时如果把 UrlMappings 放到了 src/main/groovy 路径，类上没有加 @grails.artefact.Artefact("UrlMappings") 注解，会直接导致类不会被识别为 Grails 制品，也就不会被注册为 Spring Bean。需把类移回规范路径，补全注解即可。
• 核对 Gradle 依赖配置
  打开项目根目录的 build.gradle，确认依赖块中保留了 org.grails:grails-web-boot 核心启动依赖，不要在依赖排除规则里随意移除 grails-web-mapping 模块——该模块直接提供 UrlMappings 的类型定义和自动装配逻辑，缺失会直接报找不到 Bean 的错误。
• 清除编译残留缓存
  Grails 3 和 Grails 4 的编译产物生成规则、类加载路径有明显差异，旧版本残留的缓存会打乱新的类扫描逻辑。依次执行：
  1. 运行 grails clean 清除项目编译缓存
  2. 手动删除根目录下的 build、.gradle 文件夹
  3. 重新执行依赖拉取后启动项目
• 校验启动类的扫描配置
  找到项目主启动类，检查 @SpringBootApplication 注解的 scanBasePackages 配置，确保包扫描范围覆盖了 UrlMappings 所在的根包；同时检查自动装配排除规则，确认没有误将 GrailsUrlMappingsConfiguration 配置类加入排除名单。
• 核对 Groovy 版本兼容性
  Grails 4 官方适配的 Groovy 版本为 2.5.x 及以上，很多迁移项目会保留 Grails 3 时代的低版本 Groovy 依赖，导致 Groovy 字节码校验失败，类加载器无法正常识别 UrlMappings 类。需把 Groovy 版本调整为与 Grails 4 版本匹配的官方推荐值。

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