构建缓存失效常因Git元信息或路径状态变动触发，而非代码逻辑变更；需重点排查git rev-parse、git status、.dockerignore变更及未跟踪文件等隐式依赖因素。
构建缓存失效往往不是因为代码逻辑变了，而是 git 提交元信息或路径状态的细微变动触发了重建。排查时要跳过“看代码有没有改”这种直觉，重点检查 git 层面哪些变更被构建系统（如 docker、webpack、ci 缓存、bazel）隐式依赖。
确认构建系统实际依赖的 Git 信息
不同工具读取的 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 状态
这些容易被忽略，却常导致缓存失效：
-
空提交：
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，然后运行构建脚本判断好坏
