本地调试正常但Linux服务运行JGit报Missing tree异常如何解决

问题现象 #

个人PC本地调试时，基于JGit实现的diff解析逻辑可正常运行，无异常抛出；部署到Linux服务器后，执行到diff调用逻辑时触发该异常。核心实现代码如下：

ObjectId baseObjId = oldGit.getRepository().resolve(coverageReport.getBaseVersion()); 
ObjectId nowObjId = newGit.getRepository().resolve(coverageReport.getNowVersion());            
AbstractTreeIterator newTree = prepareTreeParser(newRepository, nowObjId);
AbstractTreeIterator oldTree = prepareTreeParser(oldRepository, baseObjId);
List<DiffEntry> diff = newGit.diff().setOldTree(oldTree).setNewTree(newTree).setShowNameAndStatusOnly(true).call();

根因与对应解决方法 #

按出现概率从高到低排查：

• 浅克隆导致仓库对象缺失
  本地调试时一般拉取的是完整Git仓库，部署到Linux时如果通过CI/CD流程拉取代码时配置了浅克隆（带--depth参数），只会拉取指定深度的提交对象，历史提交关联的tree、blob对象不会被拉取到本地，访问未下载的tree对象时就会抛出该异常。
  解决方法：部署阶段拉取代码时去掉浅克隆参数，拉取完整仓库历史；如果必须保留浅克隆逻辑，执行git fetch --unshallow补全全量仓库对象，或针对要对比的两个版本单独拉取关联的所有Git对象。
• 仓库实例/对象读取器混用
  代码中用到oldGit/newGit两个独立仓库实例，如果prepareTreeParser方法实现中混用了两个仓库的ObjectReader、ObjectLoader，比如用新仓库的读取器去读旧仓库的tree对象，本地调试时可能因为仓库路径配置巧合、对象缓存命中能正常运行，Linux环境下JGit不会跨仓库扫描对象，就会报对象不存在。另外如果ObjectReader在调用diff.call()前被提前关闭，内存映射的对象文件被释放，也会触发读对象失败。
  解决方法：检查prepareTreeParser实现，解析旧版本树时必须用旧仓库的对象读取实例，解析新版本树时必须用新仓库的对象读取实例，禁止跨仓库传读取工具；确保ObjectReader生命周期覆盖整个diff调用流程，等diff执行完成后再关闭资源。
• 文件系统权限不足
  本地调试时使用个人账号，对仓库目录有完整读写权限；Linux服务一般用独立的低权限账号运行，如果该账号没有仓库.git/objects目录的递归读权限，JGit无法读取存储在磁盘上的tree对象文件，也会抛出找不到对象的异常。
  解决方法：给服务运行账号授权仓库objects目录的递归读权限，参考命令chmod -R u+r /path/to/your/repo/.git/objects，同时确认目录属主和运行账号匹配。
• 跨系统文件兼容问题
  Windows、macOS默认文件系统大小写不敏感，会自动处理CRLF/LF换行符差异；Linux文件系统大小写敏感，不会自动转换换行符。如果传入的版本号、分支名存在大小写不匹配、特殊字符转义错误，会导致resolve方法拿到的ObjectId不正确，关联的tree对象自然不存在。
  解决方法：先在Linux服务器的仓库目录下，用原生Git命令git rev-parse <传入的baseVersion值>、git rev-parse <传入的nowVersion值>，确认输出的commitId和代码中解析出的ObjectId完全一致；再执行git cat-file -t <报错的treeId>，如果原生Git也找不到该对象，说明是版本参数传错或仓库对象缺失，和JGit逻辑无关。

快速排查技巧：先在Linux服务器上用原生Git命令对两个目标版本执行diff操作，如果原生Git也报missing tree错误，可直接排除JGit代码问题，优先排查仓库完整性、权限、参数传值问题。

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