Roxi先确认你拿到的是 Git 仓库还是源码 ZIP
本文适用于 Windows、macOS、Linux 中已安装 Git 与 Git LFS 的普通工作区。只下载你有权访问的仓库对象，通常无需管理员权限。Git LFS 把指针保存在 Git 仓库里，真实文件保存在对象存储中；所以普通 Git 克隆成功不代表每个 LFS 对象已下载。
如果一个本应是图片或模型的文件只有少量文本，并含 version https://git-lfs.github.com/spec/v1、oid sha256: 和 size 三项特征，它可能是 LFS 指针。这里的内容用于识别格式，不是本次设备实测输出；不要手工改掉指针或扩展名来“修复”文件。
记录版本、当前文件和过滤条件
git --version
git lfs version
git status --short
git lfs ls-files --long
git config --get lfs.fetchinclude
git config --get lfs.fetchexcludegit config --get 查不到该项时可能无输出并返回非零状态，不等于网络失败。还要在本地检查仓库 .lfsconfig 的路径过滤项；该文件可提供 LFS 设置，Git 配置中的同项可以覆盖它。仅在本地查看自定义 endpoint，避免公开其中可能包含的内部地址或认证参数。
| 观察结果 | 更可能需要处理的地方 |
|---|---|
| git lfs 命令不存在 | 先按 Git LFS 官方项目说明安装客户端，再复查版本 |
| ls-files 中目标对应 OID 后的标记为 - | 工作区仍是指针，继续检查对象下载和回填 |
| 标记为 *，文件仍打不开 | 按文件格式和应用继续查，不先认定网络失败 |
| 目标不在 ls-files 里 | 检查当前分支、路径、LFS 跟踪属性及仓库说明 |
| 克隆不报错但没有真实文件 | 检查是否有意跳过 smudge、过滤路径或忽略下载错误 |
初始化只处理当前仓库，并留意 hook
客户端已经安装但此仓库尚未正确配置 LFS 时，先备份本地 Git 配置及现有 hook，再按需要运行 git lfs install --local。它配置当前仓库的过滤器，并可能安装 pre-push hook；不要因为遇到现有 hook 冲突就加 --force 覆盖。可用 --manual 查看如何整合原 hook。只想配置过滤器且明确暂不设置上传 hook 时，应保留 --local，使用 git lfs install --local --skip-repo；后续需要上传前应完成正常 hook 集成。
如果以前为了节省流量设置过 GIT_LFS_SKIP_SMUDGE 或 install --skip-smudge，克隆留下指针可能是预期行为。lfs.skipdownloaderrors / GIT_LFS_SKIP_DOWNLOAD_ERRORS 还可能让对象下载失败时其他 Git 操作继续成功。应先记录这些条件，不把“Git 返回成功”当作 LFS 下载成功。
选择一个文件，区分下载和回填
先备份目标文件的本地改动，确认工作区无相关合并冲突。下例 models/example.bin 是仓库相对路径占位值，必须换成 ls-files 确认的目标；origin 换成仓库实际且可信的远端名称。下载可能较大，先核对指针中的 size 及磁盘空间。
git lfs pull --include="models/example.bin" --exclude="" originpull 下载当前检出 ref 需要的对象，并在需要时更新工作区。include/exclude 是 Git LFS 路径模式；选择不含模式字符的单个路径更容易核对范围。当前 Git LFS 手册还说明：配合 Git 2.42.0 及以后版本时，索引和 .gitattributes 会影响可处理文件；稀疏检出或部分克隆需先按仓库流程确保所需属性文件可用，不能用强制下载掩盖属性缺失。
| 命令 | 作用与边界 |
|---|---|
| git lfs fetch | 下载对象到本地存储，不更新工作区；默认范围还可能受 recent 配置影响 |
| git lfs checkout | 用本地已有对象回填工作区，不联网下载；不会覆盖已修改的文件 |
| git lfs pull | 通常相当于 fetch 后 checkout，面向当前检出 ref |
| git lfs fetch --all | 用于备份或迁移的更大范围下载，不是单文件修复的默认做法 |
按实际失败层继续处理
- 如果日志显示连接超时或证书错误，记录 LFS 请求的主机名与错误类型，再检查该请求的网络路径。lfs.url 或 remote.<名称>.lfsurl 可以指定独立 endpoint，普通 Git 的成功不能证明这个地址可用。
- 遇到认证拒绝或对象缺失响应，保留对象 ID 与脱敏错误交给仓库维护者核对权限、对象是否已上传及服务限制；不要擅自改成陌生 LFS 镜像，也不要尝试绕过权限。
- 若对象已经下载而工作区仍是指针，可对同一路径运行 git lfs checkout "models/example.bin"。它不负责重新下载；有本地修改时先自行备份并决定如何处理，不执行 reset --hard 或删除工作区。
验证真实文件并结束本轮排查
- 重新运行 git lfs ls-files --long，检查目标从指针标记变为完整对象标记，并确认文件大小与该对象的预期大小相符。标记变化是回填线索，不代替应用层验证。
- 用可信应用打开该文件或执行项目提供的校验方法，不运行来源不明的下载程序。若仍失败，保留当前 ref、目标路径和对象 ID，继续查文件格式或仓库内容。
- include/exclude 命令参数只影响本次调用，无需清理全局配置；若改过持久过滤设置或初始化配置，仅恢复本轮改动及已备份 hook。已下载的对象占用磁盘，但不要在故障恢复过程中盲目 prune，以免删除仍需保留的数据。