构建缓存怎么排查 Git 提交变动引起的重建-Docker-PHP中文网

构建缓存失效常因git元信息或路径状态变动触发，而非代码逻辑变更；需重点排查git rev-parse、git status、.dockerignore变更及未跟踪文件等隐式依赖因素。

构建缓存失效往往不是因为代码逻辑变了，而是 git 提交元信息或路径状态的细微变动触发了重建。排查时要跳过“看代码有没有改”这种直觉，重点检查 git 层面哪些变更被构建系统（如 docker、webpack、ci 缓存、bazel）隐式依赖。

不同工具读取的 Git 数据不同，先明确它在用什么：

Docker 构建：常通过 git rev-parse HEAD 或 git describe --always 注入构建号；若 Dockerfile 中有 RUN git status -s 或 COPY . .，则工作区干净与否、未跟踪文件存在与否都会影响层哈希
Webpack/Vite 持久化缓存：部分插件会读取 git log -1 --format=%h 作为缓存 key；也有项目把 git diff --no-commit-id --name-only -r 结果参与 hash 计算
CI 缓存（如 GitHub Actions cache）：key 常含 ${{ hashFiles('**/package-lock.json') }}-${{ github.head_ref }}-${{ github.run_id }}，但若误用了 github.sha（每次 push 都变），哪怕只改了 README 也会失效

执行以下命令，对比两次构建间的 Git 差异：

Git Changelog Generator

使用约定式提交（Conventional Commits）从 Git 历史记录中生成结构化变更日志，支持多种格式、AI 增强型描述以及可自定义的范围……

下载

查当前提交和上一次成功构建提交（假设是 abc123）的元差异：
git diff --name-only abc123 HEAD → 看是否有意料外的文件变动（比如生成文件、.env 被意外提交）
查提交对象本身是否变化（即使内容相同）：
git show --pretty=oneline --no-patch abc123 HEAD → 观察 commit hash 是否不同，以及 author/committer 时间、邮箱是否一致（时区或本地 Git 配置不同会导致 hash 不同）
查暂存区状态是否影响 COPY/ADD：
git status -sb → 若上次构建基于干净工作区，而这次有 untracked 文件或 staged 变更，Docker 构建可能因 COPY . . 包含了新文件而重建

这些容易被忽略，却常导致缓存失效：

空提交：git commit --allow-empty -m "trigger deploy" 会生成新 commit hash，但无文件变更 —— 若构建 key 含 github.sha 就必然重建
仅修改 .gitignore 或 .dockerignore：虽然不改变源码，但会影响 COPY 或 git archive 的文件列表，从而改变构建上下文
分支指针移动：例如从 main 切到 main@{1}（reflog 中的旧位置），即使内容相同，git rev-parse main 输出也不同
提交签名或 GPG 信息变化：启用 commit.gpgSign=true 后，每次提交 hash 都不同，且签名块本身会被某些工具读取

确认问题后，针对性修复：

构建 key 中避免直接使用 github.sha，改用 hashFiles('**/src/**', '**/package.json') 等内容感知方式
Docker 构建前加 git clean -fdx && git reset --hard，确保工作区与索引严格一致
CI 脚本中显式导出稳定版本标识：
echo "BUILD_VERSION=$(git describe --tags --abbrev=0 2>/dev/null || git rev-parse --short HEAD)" >> $GITHUB_ENV
用 git bisect 快速定位哪次提交开始失效（如果问题是最近引入的）：
git bisect start && git bisect bad && git bisect good v1.2.0，然后运行构建脚本判断好坏