如何向Magnolia CMS添加自定义Java模块并解决模板不显示问题

高频配置错误点 #

• 模块未被webapp实际加载
  先检查打包后的webapp的WEB-INF/lib目录下是否存在你的自定义模块jar包。多数场景是只在父POM声明了模块依赖，没有在Magnolia webapp子模块的POM中添加对应runtime依赖，Magnolia启动时根本不会扫描到你的模块，自然不会注册其中的模板。
• 模块描述符配置错误
  检查模块配置文件src/main/resources/META-INF/magnolia/<your-module-name>.xml：
  • 必须显式声明对pages、rendering核心模块的依赖，保证你的模块在核心模块初始化完成后再启动，避免模板注册时核心服务未就绪导致注册失败
  • 不要写错模块名、版本号，配置错误的模块会在启动阶段直接被跳过，日志中会打印模块加载失败的WARN信息
• 模板文件路径/定义不符合规范
  • Magnolia默认将页面模板识别路径设为模块资源目录下的templates/pages/，如果你把页面模板定义（yaml/xml格式）放到了templates/components/等其他路径，又没有自定义模板扫描规则，Pages App不会将其识别为可用页面模板
  • 页面模板定义必须包含title、renderType、templateScript三个必填属性，缺任意一个都会导致模板注册失败
  • *注意：模板ID格式固定为<模块名>:<模板相对路径>，全局不能重复，重名模板会被其他模块的配置覆盖
• 模板可见性/可用性配置错误
  • 检查模板定义中的visible属性，若被设为false不会出现在模板选择列表中
  • 检查availability权限规则：如果配置了角色限制，当前登录的非admin账号没有对应权限就看不到模板；如果配置了站点绑定规则，必须在对应站点定义的templates.availability列表中加入你的自定义模板，否则站点下新建页面时不会展示该模板
• 开发环境缓存问题
  若没有在magnolia.properties中配置magnolia.develop=true开启开发模式，修改模板配置后不会触发热重载，需要重启应用，或进入JCR控制台删除/modules/<your-module-name>/templates节点触发模块重新注册，再硬刷新Pages App页面。
• Java组件扫描失败
  如果你通过@Template、@Renderer等注解注册自研Java组件对应的模板/渲染器，必须保证注解所在的包路径被Magnolia类扫描器覆盖，否则自定义渲染器不会被实例化，绑定了该渲染器的模板会因为依赖缺失加载失败。

备用排查/实现路径 #

如果以上排查点都没有定位到问题，按以下步骤操作：

1. 用官方空白模块archetype生成标准模块骨架，不要从零手写模块配置，将你的自研Java代码、模板资源按骨架的标准目录结构迁移，避免手写配置的笔误。
2. 先剥离所有自定义Java逻辑，写一个最小化测试页面模板：仅配置必填属性，绑定一个只输出简单文本的Freemarker渲染脚本，确认这个测试模板能正常在Pages App中显示后，再逐步集成自研Java组件，每集成一部分就验证一次，精准定位导致加载失败的代码/配置段。
3. 启动时将Magnolia的日志级别调整为DEBUG，搜索你的模块名、模板ID关键字，所有模板注册失败的场景都会打印明确的错误栈和原因，不需要盲目试错。

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