Vaadin 14.6版本@CssImport注解无法加载自定义CSS是否为bug？

问题背景 #

我们此前使用Vaadin 14.5版本时，@CssImport注解加载自定义CSS功能正常。升级到14.6.0及以上版本后，@CssImport不再加载自定义CSS。

项目结构 #

Maven结构如下：

- app-1、app-2等：存放业务代码和样式的应用
- shared：多应用共享的公共代码和样式
 |
 +- src/main/java/our/package/AbstractUI.java
 |
 +- src/main/resources/META-INF/resources/frontend/
    |
    +- css
       |  
       +- styles.css
       |
       +- vaadin-vertical-layout.css

原有配置逻辑 #

1. 共享模块中定义了针对Shadow DOM的自定义样式，vaadin-vertical-layout.css内容如下：

/* Page */
:host(.Page) {
    left: 64px;
    padding-top: 2em;
    position: absolute;
    transition: all 0.5s ease;
    width: calc(100% - 64px);
}

2. 所有UI类的父类AbstractUI中统一配置样式加载注解：

@StyleSheet("./css/styles.css")
// 其他注解省略
@CssImport(value = "./css/vaadin-vertical-layout.css", themeFor = "vaadin-vertical-layout")
@Theme(value = Material.class, variant = Material.LIGHT)
public abstract class AbstractUI extends VerticalLayout { 
// 类逻辑省略
}

上层业务应用无需额外配置样式注解，仅需继承AbstractUI即可自动加载对应样式，注入到对应组件的Shadow DOM中。

异常表现 #

该逻辑在Vaadin 14.0~14.5.5版本均正常运行，升级到14.6.0之后出现如下问题：

• vaadin-maven-plugin构建时能正常检测CSS文件存在，文件缺失会正常报错终止构建
• 应用运行时@CssImport配置的样式未实际加载
• @StyleSheet注解功能完全正常，对应全局CSS可以正常加载

原因与解决方法 #

该问题不属于Vaadin的bug，是14.6版本引入的前端注解扫描性能优化导致的默认行为变更：
14.6版本为了提升启动速度，默认关闭了父类注解递归扫描逻辑，仅会扫描直接标注在@Route路由类上的@CssImport、@JsModule这类前端资源注解，不会递归扫描父类的对应注解。而@StyleSheet属于全局样式注解，扫描逻辑未做调整，因此能正常生效。

可根据项目情况选择以下任意一种方案解决：

• 方案一：开启旧版扫描逻辑
  如果你不想调整现有代码结构，直接在项目配置文件中添加如下配置即可恢复旧版递归扫描行为：

  vaadin.useLegacyFrontendAnnotationScanning=true
  

  Spring Boot项目加在application.properties中，普通Vaadin项目加在vaadin.properties中即可。
• 方案二：调整注解放置位置
  把所有@CssImport注解移到每个带@Route注解的业务路由类上，或者单独封装一个标注了所有@CssImport的配置类，在路由类上通过@Import引入即可。
• 补充检查：调整路径写法
  14.6版本也调整了前端资源相对路径的解析逻辑，可尝试去掉@CssImport路径前的./，修改为如下写法：

  @CssImport(value = "css/vaadin-vertical-layout.css", themeFor = "vaadin-vertical-layout")
  

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