Apereo CAS从6.6.6升级至7.0.5.1后自定义HTML页面无法加载

核心问题定位 #

升级后自定义登录页和默认页均无法正常渲染，说明问题出在页面加载的核心逻辑或模板配置层面，而非单纯的自定义路径错误。

排查与修复步骤 #

• 验证模板引擎配置
  CAS 7.x 默认使用Thymeleaf 3.x，对比6.6.x版本存在模板解析规则变化。检查cas.properties中以下配置是否准确：

  cas.view.template.engine.enabled=true
  cas.view.template.cache=false # 开发环境禁用缓存，避免页面更新不生效
  cas.view.template.prefix=classpath:/templates/
  cas.view.template.suffix=.html
  

  同时确认src/main/resources/templates/login/casLoginView.html的目录结构完全符合要求。

• 清理构建缓存与产物
  升级残留的旧缓存可能干扰模板加载：

  • 执行./gradlew clean build（Gradle项目）或mvn clean package（Maven项目），彻底清除旧class文件和资源。
  • 删除服务运行目录下的target/build临时目录，重启CAS服务。

• 确认默认模板依赖
  移除自定义页面后仍无法显示默认页，大概率是缺失默认模板依赖。CAS 7.x的默认登录页模板在cas-server-webapp-templates模块中，需确保项目依赖已正确引入：

  // Gradle示例
  implementation "org.apereo.cas:cas-server-webapp-templates:7.0.5.1"
  

  Maven依赖配置：

  <dependency>
      <groupId>org.apereo.cas</groupId>
      <artifactId>cas-server-webapp-templates</artifactId>
      <version>7.0.5.1</version>
  </dependency>
  

  依赖缺失会导致CAS找不到默认模板，进而显示异常界面。

• 开启DEBUG日志定位
  增加Thymeleaf和CAS视图层的DEBUG日志输出：

  logging.level.org.thymeleaf=DEBUG
  logging.level.org.apereo.cas.web.view=DEBUG
  

  重启服务后，查看日志中是否存在Template not found或Template resolution failed类错误，此类信息可直接定位模板加载失败的具体原因。

• 检查自定义页面资源引用
  自定义登录页若引用CAS内置静态资源（如css、js），需确认路径是否适配7.x版本。正确的资源引用格式示例：

  <link th:href="@{/css/cas.css}" rel="stylesheet"/>
  

  路径错误会导致页面渲染异常，甚至显示空白或错误界面。

总结 #

优先排查模板引擎配置、默认模板依赖完整性和缓存问题，借助DEBUG日志定位具体故障点。确保自定义页面路径严格匹配CAS 7.x规范，同时验证静态资源引用路径的正确性。

内容的提问来源于stack exchange，提问作者Abhishek-M