Keycloak自定义主题引用自定义字体的正确路径配置问询

核心错误原因 #

你当前用的font-url()是Sass/LESS等CSS预处理器的专属方法，原生CSS不支持该语法，这是加载失败的核心原因。

修复步骤 #

1. 修改CSS字体声明语法 #

将所有font-url替换为标准CSS的url()，相对路径你原本的写法是对的，不需要修改：

@font-face {
    font-family: "font-name";
    font-style: normal;
    font-weight: 400;
    src: url("../fonts/font-name.woff2") format("woff2"),
         url("../fonts/font-name.woff") format("woff"),
         url("../fonts/font-name.ttf") format("truetype");
}
body {
    font-family: "font-name" !important;
}

2. 清空主题缓存测试 #

Keycloak默认会缓存所有主题资源，修改代码后必须清空缓存才会生效：

• 进入Keycloak管理控制台，点击顶部左侧「服务器信息」
• 切换到「缓存」标签页，找到「主题」缓存项，点击「清空缓存」
• 刷新登录页验证字体是否生效

备选低出错方案 #

如果以上修改还是不生效，可以把资源迁移到login模块下，避开common模块的资源映射逻辑，几乎不会出现路径问题：

调整后文件结构 #

└── theme/
    └── my-theme/
        └── login/
            ├── *.ftl
            ├── messages/
            │   └── *.properties
            ├── theme.properties
            └── resources/
                ├── css/
                │   └── my-style.css
                └── fonts/
                    ├── font-name.woff
                    ├── font-name.woff2
                    └── font-name.ttf

调整theme.properties配置 #

去掉import配置，只保留以下内容：

parent=base
styles=css/my-style.css

验证方法 #

如果还是不生效，可以直接在浏览器访问字体文件地址排查：
假设你的Keycloak访问地址为http://localhost:8080，版本号为21.1.1，主题名为my-theme，那么字体文件的直接访问地址为：
http://localhost:8080/resources/21.1.1/my-theme/fonts/font-name.woff2
如果能直接下载文件说明资源路径配置正确，问题出在CSS语法或者缓存；如果返回404说明文件存放路径或主题配置错误。

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