Keycloak源码构建失败：keycloak-themes与keycloak-guides报错

17.0.0版本能正常构建、更高版本报两个模块错误，核心原因是18.0.0版本迭代后加了几个官方构建文档没写全的环境约束，尤其是Windows环境下的适配要求没明确标注，对应问题和解决方法如下：

未在官方文档说明的前置要求 #

• 全局编码必须强制为UTF-8，Windows系统默认GBK编码会直接导致文档模块解析失败
• 项目存放路径不能过长，不能包含空格、特殊字符，否则前端插件调用npm时会触发Windows路径长度限制报错
• 不要用过高版本的JDK，虽然文档标注支持Java 11，但不要用Java 17及以上版本构建18.0.0标签版，会触发依赖不兼容
• Node.js版本要和项目配置匹配，18.0.0对应Node 16.x，最新main分支对应Node 18.x，版本差太多会导致前端依赖安装失败

两个报错的对应修复方案 #

keycloak-guides模块UTF-8编码错误 #

报错里的invalid byte sequence in UTF-8是asciidoctor插件调用JRuby时读取了系统默认编码导致的，和文档内容本身无关：

• 构建前在CMD窗口执行set MAVEN_OPTS=-Dfile.encoding=UTF-8，PowerShell窗口执行$env:MAVEN_OPTS="-Dfile.encoding=UTF-8"，强制JVM使用UTF-8编码运行
• 如果不需要生成官方指南文档，直接在构建命令里加-DskipGuideDocs参数跳过这个模块，完全不影响核心功能编译

keycloak-themes模块npm执行错误 #

退出码-4058是Windows环境下「找不到可执行文件」的典型错误，是frontend-maven-plugin自动下载node/npm时因为路径过长、网络问题导致文件缺失：

• 把项目源码移到磁盘根目录的短路径下，比如C:\kc\，不要放在C:\Users\xxx\IdeaProjects\这种多层长路径目录下，避开Windows默认260字符路径长度限制
• 删掉本地Maven仓库里com/github/eirslett目录下的所有缓存，重新构建让插件重新拉取对应版本的node
• 手动安装对应版本的Node.js并配置到系统PATH，构建时加-Dfrontend.install.nodeAndNpm=false参数跳过插件自动下载步骤，直接用本地安装的node/npm执行前端构建

稳定构建命令参考 #

不需要跑测试、不需要生成文档、不需要打javadoc的话，直接用下面的命令可以绕开大部分非核心模块的构建问题：

mvn clean install -DskipTests -DskipGuideDocs -Dmaven.javadoc.skip=true

小提示：如果之前构建失败过，一定要先执行mvn clean把之前构建生成的残次文件删掉，再重新执行构建，否则残留的损坏文件会导致重复报错。

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