MacOS环境下git checkout检出PNG文件仅获取到Git LFS指针文本
故障核心定位
你遇到的本地PNG文件内容为Git LFS指针文本的问题,本质是本地Git环境未正常挂载Git LFS大文件拉取能力,和远端仓库存储内容、BitBucket网页端展示逻辑无关——Windows用户可以正常检出,是因为Windows端的Git安装包默认内置LFS支持且完成了全局初始化,和你本地Intel架构MacOS上的Git环境存在配置差异。
你之前尝试的删除./git/index后reset、全量删除本地仓库重新克隆的操作没有效果,是因为这些操作全程没有触发LFS的拉取流程,Git遇到标记为LFS的文件时直接将仓库内存储的纯文本指针写入了本地磁盘,自然永远无法得到真实的PNG内容。
分步解决操作
- 第一步:确认LFS客户端安装状态
在终端执行git lfs --version检查Git LFS客户端是否可用:- 如果终端提示
git-lfs: command not found,说明当前环境根本没有安装Git LFS客户端:你当前使用的2.23.0版本Git是早期MacOS自带的预装版本,本身不附带LFS组件,需要先安装和当前Git版本兼容的LFS客户端 - 如果能正常输出LFS的版本号,说明客户端已存在,接着执行
git lfs install重新将LFS的过滤钩子注册到Git全局配置中,修复之前钩子失效导致的拉取跳过问题
- 如果终端提示
- 第二步:批量替换本地的指针文件为真实内容
在本地仓库根目录执行git lfs checkout,Git会自动识别所有本地路径下的LFS指针文件,从远端拉取对应的真实二进制内容覆盖本地文本文件,不需要再重复删仓库、重新克隆的操作 - 第三步:配置全局LFS拉取规则,避免后续再次出现同类问题
依次执行两条配置命令,确保Git检出文件时能自动触发LFS流程:- 执行
git config --global filter.lfs.smudge "git-lfs smudge -- %f" - 执行
git config --global filter.lfs.process "git-lfs filter-process"
配置完成后,后续执行分支切换、新仓库克隆操作时,Git会自动完成LFS文件的拉取,不会再直接把指针文本写入本地磁盘。
- 执行
补充验证
操作完成后,可以任意打开一个之前显示为文本的PNG文件,如果能正常预览图片内容,就说明故障完全修复。
内容的提问来源于stack exchange,提问作者Frank-Rene Schäfer
相关产品推荐
相关产品推荐

