Git LFS 指针文件 — 二进制为何变成文本

检查 smudge 过滤器、attributes 与 lfs 状态，安装钩子并拉取对象，解决 Git LFS 指针未展开导致构建读取到文本的问题。

现象

图片、模型或压缩包打开后只有一小段以 version https://git-lfs.github.com/spec/v1 开头的文本；工作区文件只有几百字节而非数 MB；构建报“无法识别的图片”或“文件提前结束”；CI 检出后资源仍是指针。

诊断

先确认文件确实是指针：

file assets/model.bin
head -3 assets/model.bin
wc -c assets/model.bin
git lfs ls-files | head -20
git check-attr filter diff merge -- assets/model.bin
git config --get filter.lfs.smudge

指针包含 oid 与 size 行，工作区大小远小于真实对象。git lfs ls-files 中路径带星号表示本地已有对象；git check-attr 输出 filter: lfs 才说明该文件由 LFS 管理。若没有 smudge 命令，说明当前克隆没有安装 LFS 钩子；若过滤器正常但对象缺失，则是没有拉取成功或远端缺少对象。

修复

安装钩子并拉取内容：

git lfs install
git lfs pull
git lfs checkout

CI 中应在 checkout 步骤启用 LFS，或在检出前执行 git lfs install --force。如果文件在 .gitattributes 生效前就按普通 blob 提交，需要补规则并迁移历史：

git lfs track "*.psd"
git lfs migrate import --include="*.psd" --everything

迁移会改写提交 ID，必须与团队约定时间并谨慎强制推送。

验证

file 能识别真实格式，wc -c 与指针中的 size 一致，git lfs ls-files 对应路径带 *。重新构建确认资源能正常加载，并从全新克隆跑一次 CI，排除只是依赖本地 LFS 缓存的情况。