G
GitIgnore.pro
🚀 Deploy-ready Checklist

CI/CD 友好的 .gitignore:产物隔离、缓存与流水线安全

谁在提交构建产物?为什么流水线缓存突然被清空?这份指南帮助你梳理 CI/CD 环境下的忽略策略,保证构建/测试/部署三阶段的文件只在该出现的地方出现。

01. 三阶段视角:构建、测试、部署分别忽略什么?

构建阶段

  • 忽略本地编译产物(dist/, build/, target/)
  • 排除打包缓存(.cache/, .turbo/, .parcel-cache/)
  • 保留 manifest & lockfile,方便重建依赖

测试阶段

  • 清理测试快照与覆盖率(coverage/, junit.xml)
  • 隔离 e2e 工具输出(playwright-report/, cypress/videos/)
  • 避免报告文件被忽略(例如 junit.xml 需要上传时,改用 artifacts)

部署阶段

  • 阻止 secrets/.env 被 commit(使用 `!**/.env.example` 保留模板)
  • 忽略临时打包目录(.serverless/, .vercel/output/)
  • 确保 Docker context 清晰(.dockerignore 与 .gitignore 区分)

✅ 建议在项目 Wiki 中维护「阶段 → 产物 → 存储位置」对照表:哪些文件上传到构建产物服务器、哪些被忽略、哪些写入 artifacts。

02. 常见框架的忽略策略

  • Next.js / Vite 前端:需要忽略 .next/out/dist/.vercel/。CI 中使用 next export 时,将输出移动到 artifacts/ 再上传。
  • Node.js 后端:忽略 logs/tmp/prisma/client/ 生成目录。保持 .env* 不提交,使用 secrets 注入。
  • Python 数据管线:忽略 __pycache__/.pytest_cache/mlruns/ 等实验目录,模型发布到对象存储或 Git LFS。

部署产物管理

  • • 使用 artifacts/ 作为临时输出目录,CI 完成后删除或上传
  • • Docker 打包时维护 .dockerignore,避免将 node_modules打入镜像
  • • Serverless 框架的 .serverless/.terraform/ 等目录必须忽略

03. CI 前置校验脚本(Bash 示例)

将脚本作为部署前置步骤,可快速捕捉被误追踪的敏感文件和产物。

#!/usr/bin/env bash
# scripts/ci-verify-gitignore.sh

set -euo pipefail

echo "Running gitignore validation before deployment..."

# 1. 确认 .env* 未被追踪
if git ls-files --cached | grep -E '\\.env(\\..+)?$' >/dev/null; then
  echo "::error::Found tracked .env file"
  git ls-files --cached | grep -E '\\.env(\\..+)?$'
  exit 1
fi

# 2. 校验 build 目录是否被忽略
if [ -d "build" ] && git check-ignore build >/dev/null; then
  echo "Build folder ignored as expected ✔"
else
  echo "::warning::build/ not ignored. Did you rename output path?"
fi

# 3. 确认 artifacts 目录存在(用于上传而非提交)
mkdir -p artifacts
echo "Artifacts folder ready: $(pwd)/artifacts"

可在 GitHub Actions / GitLab CI 中执行,并添加 --strip-trailing-cr 防止 Windows 换行导致 diff。

04. 缓存 & 工件策略:让流水线提速同时保持干净

缓存目录命名

  • • 使用 .cache/.turbo/.parcel-cache/ 等统一前缀,便于 ignore
  • • 避免与实际代码目录重名,降低错误提交风险
  • • 在 README 中注明如何清理缓存,保证新成员上手顺利

Artifacts vs Git 提交

  • • 构建产物应上传到 artifact / 对象存储,不应 commit 到仓库
  • • 发布流程建议:构建 → 上传 artifact → 由部署任务下载 → 产物只在流水线存在
  • • 只有「不可再生成」的文件(如 icon 手工导出)才考虑纳入版本库

05. Checkpoints:将 .gitignore 纳入 CI 审查流程

PR 模板提示: 在 PR 模板加入「是否修改 .gitignore?是否更新文档?」的问题,让审核人关注。
⚙️
钩子链路: commit-msg → pre-commit → CI job → 部署前脚本,全链路验证忽略规则是否生效。
🧪
Playwright / Cypress 视角: 将生成的测试报告保存在 `artifacts/` 并忽略,其路径由 CI 上传,不污染仓库。
🛡️
Secrets 管理: `.env`, `*.pem`, `service-account.json` 必须忽略;提供 `.env.example` 模板并写清加载方式。

06. 延伸链接与最佳实践

  • Monorepo 场景:多包仓库可结合 Monorepo .gitignore 架构管理包级构建产物,再由流水线分阶段清理。
  • 大文件管理:如果流水线涉及模型或设计稿,配合Git LFS 最佳实践统一追踪与审计脚本。
  • 自动化工具:在 PR 流程中加入 ValidatorDiff,确保忽略规则持续生效。

07. FAQ:流水线常见疑问

为什么 Build 目录仍然出现在仓库?

检查是否存在包级 .gitignore 覆盖,或部署脚本在构建后执行了 git add .。可在流水线中运行git status --ignored 检查忽略状态。

如何安全地处理 .env?

将实值存储在 CI Secret 或密钥管理中,仅提交 `.env.example` 模板。Validator 可以用来确认 `.env` 未被追踪。

Artifacts 应该提交吗?

不建议。请改用 CI 的 artifact/upload 机制,将构建结果存储在临时存储或对象存储中,保持仓库轻量。

让流水线持续保持干净

为 CI/CD 生成防漏模板

使用生成器快速组合 build、test、deploy 阶段的忽略规则,并在流水线里自动校验。