AEM 6.2 SP1升级至6.4后部分包无法安装问题求助

我之前帮团队处理过类似的AEM升级坑，来给你捋清楚问题根源和解决步骤：

问题到底出在哪？ #

• 升级时部分系统包没被正确替换，新旧版本共存，直接触发版本校验报错：A different version seems to be installed:
• AEM 6.4对UI组件API做了大重构，旧的com.day.cq.widget.HtmlLibraryManager被迁移到com.adobe.granite.ui.clientlibs.HtmlLibraryManager，但未升级成功的包还在引用旧API
• 你手动修改/libs下的系统文件后，破坏了Oak维护的核心系统属性rep:externalId——这是Oak用来追踪系统节点的关键属性，动它肯定会触发约束异常：javax.jcr.nodetype.ConstraintViolationException: OakConstraint0074: Attempt to add, modify or remove the system maintained property 'rep:externalId'

分步解决，一步都不能少 #

1. 先搞定包版本冲突 #

• 登录AEM包管理器（http://<host>:<port>/crx/packmgr/index.jsp），找到那些报版本冲突的包
• 彻底卸载+删除旧版本：选中旧包先点「Uninstall」，等卸载完成一定要点「Delete」把它彻底清掉，残留的旧文件会一直跟新版本打架
• 清缓存重启：重启AEM实例，或者去OSGi控制台（http://<host>:<port>/system/console/bundles）找到com.adobe.granite.ui.clientlibs相关bundle，依次点「Refresh」和「Update」

2. 正确更新API引用（别直接改/libs！） #

手动改/libs下的文件是大忌，这是AEM系统维护的目录，改了以后官方包安装肯定冲突。正确姿势是用Overlay机制：

• 在/apps目录下复刻对应路径，比如创建/apps/cq/ui/components/widget/html.jsp
• 在这个自定义文件里引用新API，示例代码：

  <%@page import="com.adobe.granite.ui.clientlibs.HtmlLibraryManager"%>
  <%@page import="org.apache.sling.api.resource.ResourceResolver"%>
  <%
    ResourceResolver resolver = slingRequest.getResourceResolver();
    HtmlLibraryManager htmlLibManager = resolver.adaptTo(HtmlLibraryManager.class);
    // 后面的业务逻辑跟原来保持一致就行
  %>
  

• 这样既实现了API更新，又不会碰系统文件，后续装官方包完全没问题

3. 修复rep:externalId的约束异常 #

如果已经手贱改了/libs下的文件导致这个错误，先把系统文件恢复回来：

• 从纯净的AEM 6.4实例里导出/libs/cq/ui/components/widget目录，导入到当前实例覆盖修改后的文件
• 或者用CRXDE Lite（http://<host>:<port>/crx/de/index.jsp）找到该节点，右键选「Restore from Repository」（前提是有版本历史）
• 恢复完再按步骤2用Overlay来做自定义修改

升级前必做的预防措施 #

• 升级前一定要跑官方的Pre-Upgrade Check Tool，提前排查包冲突和API兼容性问题
• 自定义代码提前做API兼容性测试，6.2到6.4的API变更不少（比如JCR到Oak的底层升级、UI组件的重构）
• 记住AEM的核心原则：永远别直接改/libs，所有自定义都放/apps

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