Unity导入Git LFS托管自定义包时LFS文件加载失败问题

问题场景 #

使用Unity 2022.3.22f开发项目，主项目依赖多个存储在独立GitHub仓库的自定义包，这些包包含Git LFS追踪的大文件。单独克隆每个包仓库时，LFS文件可正常下载；但克隆主项目仓库后，由Unity基于package.json通过SSH自动导入自定义包时，仅非LFS文件能正确克隆，LFS追踪文件（如.png）仅显示元数据占位符，无法加载实际内容，导致Unity报错。

已尝试的排查操作 #

• 执行git lfs install配置Git LFS
• 重装Git和Git LFS（版本3.6.1）
• 重新配置GitHub SSH密钥
• 使用SSH URL克隆仓库
• 清理Unity缓存

排查方向与解决方案 #

1. 校验Git LFS的全局/仓库级配置 #

• 查看全局配置：执行git config --global -l | grep lfs，确认以下配置项存在且正确：

  filter.lfs.process=git-lfs filter-process
  filter.lfs.smudge=git-lfs smudge -- %f
  filter.lfs.clean=git-lfs clean -- %f
  

• 若全局配置正常，进入主项目根目录执行git config --local -l | grep lfs，检查仓库级配置是否覆盖了全局的正确设置。

2. 强制Unity使用系统Git而非内置Git #

Unity默认内置的Git客户端可能与系统Git LFS不兼容：

• 打开Unity编辑器，进入Edit > Preferences > Version Control
• 将Version Control Mode设为Visible Meta Files，Git Client选择System Git，并确保路径指向你安装的Git可执行文件（如Windows下的C:\Program Files\Git\cmd\git.exe，Linux/macOS下的/usr/bin/git）
• 重启Unity后重新导入自定义包

3. 手动触发LFS拉取自定义包 #

找到Unity自动下载的自定义包路径（一般位于Library/PackageCache/下对应包的文件夹），进入该目录执行：

git lfs pull

若能成功拉取，说明Unity自动导入时未触发LFS拉取流程，可考虑在包的package.json中添加postinstall脚本，自动执行LFS拉取操作。

4. 检查SSH配置对Git LFS的支持 #

Git LFS通过SSH传输时，需确保SSH配置未拦截LFS请求：

• 打开SSH配置文件（Windows为C:\Users\<你的用户名>\.ssh\config，Linux/macOS为~/.ssh/config），确认没有针对GitHub的特殊配置限制LFS命令。
• 执行日志追踪命令排查连接问题：
  • Linux/macOS：GIT_TRACE=1 git lfs pull
  • Windows：set GIT_TRACE=1 && git lfs pull
    查看日志输出定位是否存在SSH权限或连接异常。

5. 重置Git LFS钩子 #

若LFS钩子文件损坏，执行以下命令强制重新安装：

git lfs install --force

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