Git 浅克隆通过限制拉取的提交历史深度减少网络传输和磁盘 IO，适合大多数只关注当前代码状态的 CI 构建任务。主要风险是导致依赖完整提交历史的版本号生成逻辑或代码分析工具失效。
先说结论：在 CI 环境中启用浅克隆能显著减少克隆耗时，但需确认构建脚本不依赖完整 Git 历史。
- 先定位：确认构建流程是否使用 git describe 或基于 commit count 的版本号生成。
- 先做：在 CI 配置文件中设置 fetch-depth 为 1 或使用 git clone `--depth`=1。
- 再验证：检查构建日志中的克隆耗时及版本号生成是否正确。
命令速用版
本地测试浅克隆效果可使用以下命令：
git clone `--depth`=1 <repository_url>GitHub Actions 配置示例：
- uses: actions/checkout@v4
with:
fetch-depth: 1为什么会这样
浅克隆只获取指定层数的提交对象，不包含完整的祖先链。
默认 Git 克隆会下载所有分支的全部历史对象，仓库存在时间越长数据量越大。浅克隆参数 `--depth` 告诉 Git 只获取最近 N 次提交的历史截断视图，直接减少网络下载量和本地对象存储占用，从而缩短 CI 准备阶段时间。
分步处理
第一步：修改 CI 配置文件。
在 Jenkinsfile、.gitlab-ci.yml 或 GitHub Actions workflow 中找到 checkout 步骤。将克隆深度参数设置为 1。如果使用 actions/checkout 插件，设置 fetch-depth: 1。
第二步：检查构建脚本兼容性。
搜索构建脚本中是否包含 git describe、git rev-list `--count` HEAD 或依赖 tag 距离的逻辑。如果存在，需评估是否改为基于文件版本号或接受浅克隆限制。
第三步：配置例外回滚。
如果特定任务需要完整历史，可在该任务步骤前执行 git fetch `--unshallow` 恢复完整历史，但这会抵消浅克隆带来的性能收益。
怎么验证是否生效
在 CI 构建日志中观察 git clone 或 checkout 步骤的耗时变化。
执行命令 git rev-list `--count` HEAD 检查当前提交数量。浅克隆深度为 1 时，输出结果应为 1。如果输出数字大于 1，说明仍拉取了部分历史。
常见坑
依赖 git describe 生成版本号会报错 fatal: No names found, cannot describe anything，因为浅克隆默认不拉取 tag 信息。
部分静态分析工具需要对比父提交差异，浅克隆可能导致找不到父 commit 哈希。
子模块初始化有时需要完整历史才能正确解析特定提交，需测试子模块 checkout 是否正常。
常见问题
浅克隆会影响编译出的二进制文件吗
不会影响编译结果，除非构建脚本将 Git 提交哈希写入二进制文件。
如何临时恢复完整历史
在需要完整历史的步骤前运行 git fetch `--unshallow` 命令即可恢复。
浅克隆支持拉取特定分支吗
支持，配合 -b 参数指定分支名称，仍只拉取该分支的最新深度历史。
参考来源
Git 官方文档 - git-clone 手册 https://git-scm.com/docs/git-clone
GitHub Actions 文档 - actions/checkout 用法 https://github.com/actions/checkout