CI 里的 LFS 是什么情况
CI 上使用带 LFS 的仓库有个取舍：作业不需要大文件内容时跳过下载（省流量、提速），需要时确保环境里 LFS 可用并完成拉取。检出默认只取指针文件——如果作业直接读大文件，拿到的是指针文本而不是真实内容，报错往往不直观。
基本信息
| 跳过内容 | 设 GIT_LFS_SKIP_SMUDGE=1 再克隆或检出 |
|---|---|
| 需要内容 | 安装 git-lfs，执行 git lfs install 与 git lfs pull |
| 按路径拉取 | git lfs pull --include='assets/**' |
| 校验 | git lfs ls-files 看清单，注意大小是否真实体量 |
| 缓存 | 缓存 LFS 对象目录可减少重复下载，缓存键带上属性文件指纹 |
| 环境检查 | git lfs version 确认工具已装且版本符合要求 |
典型使用场景
- 纯代码检查作业（lint、单测不涉及大文件）：跳过下载提速
- 构建打包作业：需要真实资源，装 LFS 并拉取后再执行
- 多作业流水线：把 LFS 拉取收敛成前置步骤或缓存层
- 排查文件内容是指针文本：确认作业是否安装了 git-lfs 与执行过 pull
- 缓存策略：按仓库与属性文件指纹隔离 LFS 缓存
常见写法
常见写法
# 只跑代码检查：跳过内容下载
export GIT_LFS_SKIP_SMUDGE=1
git clone --depth 1 https://example.com/app.git
# 需要大文件时
git lfs install --local
git lfs pull --include='assets/**'
git lfs ls-files --size # 核对真实体量CI 场景对照
| 作业类型 | 做法 | 注意 |
|---|---|---|
| 纯代码检查 | 跳过 smudge 下载 | 作业里别读大文件 |
| 构建打包 | 安装 LFS 并 pull | 确认版本与缓存 |
| 缓存层 | 缓存 LFS 对象目录 | 缓存键含仓库标识与属性指纹 |
多数托管平台的检出步骤需要显式开启 LFS 或安装工具；先看平台文档，再在本地复现同样的命令验证；版本固定的自定义镜像最省心。
git lfs ls-files --size 可快速验证：数字接近文件真实大小说明拉取成功，只有指针大小说明仍是指针，补跑一次 git lfs pull 再复验作业。