ThinkPHP 项目 Git 管理必须严格执行规则：runtime/ 需用 git rm -r --cached 彻底移除；版本回退后立即 php think clear 清缓存；分支名强制规范为 main/release/vX.Y.Z/feature/xxx/fix/xxx；配置变更优先 cherry-pick 而非 revert；.env 忽略、.env.example 提交；composer.lock 必须提交。
ThinkPHP 项目用 Git 管理，核心不是“能不能”，而是“不按规则来，第二天就出事”。runtime 缓存没忽略、.env 被提交、分支名随意写——这些不是小问题，是 CI 失败、线上白屏、协作卡壳的直接原因。
runtime/ 目录必须从 Git 中彻底移除
ThinkPHP 每次请求都会往 runtime/ 写日志、模板缓存、路由缓存，它天生就不该进版本库。但很多人加了 .gitignore 还是总看到 runtime/log/202605/xx.log 在 git status 里飘红——那说明它早被 track 过了。
- 确认
.gitignore里有这一行：/runtime/（开头带斜杠，避免匹配错名） - 执行
git rm -r --cached runtime/，清 Git 缓存但保留本地文件 - 再
git commit -m "remove runtime from git tracking" - 漏掉第二步？下次
git pull后runtime/下的文件仍会持续报红，CI 构建很可能因“脏工作区”失败
回滚 ThinkPHP 版本时，git reset 后必须立刻清缓存
只退代码不清理 runtime/，旧版代码会加载新版编译的模板或配置缓存，轻则 500，重则 ClassNotFoundException。这不是 Bug，是 ThinkPHP 的运行机制决定的。
- 先停服务或切走流量（防止新请求写入缓存）
- 执行
git reset --hard <commit-hash> - 立刻运行
php think clear（TP6+）或php think cache:clear（TP8） - 检查
runtime/log/是否还有 PHP Fatal 错误——有就说明缓存没清干净 - CI/CD 部署脚本末尾建议固定加上这句，别依赖人工补救
分支命名不统一，feature/login 和 feat/login 混用会出事
Git 不校验分支名，但人会看错。有人 git checkout dev 切到的是别人建的 develop 分支，merge 时把未测功能推上 release，这种事在 ThinkPHP 团队里发生过不止一次。
批量替换指定目录下所有 Git 仓库的远程地址（remote URL）。 当用户需要将 Git 仓库从一个服务器迁移到另一个服务器时使用。 触发词：git remote 替换、git url 批量修改、git 仓库迁移、更换 git 地址、批量修改 remote url。
立即学习“PHP免费学习笔记（深入）”；
- 强制前缀：只允许
main、release/vX.Y.Z、feature/xxx、fix/xxx（全小写 + 短横线） - 禁止
dev、develop、feat/、feature_login、feature/login - 在
.git/hooks/pre-commit里加校验：git branch --show-current | grep -E '^(main|release/|feature/|fix/)' >/dev/null || { echo "branch name invalid"; exit 1; } - 把这个规则写进根目录的
CONTRIBUTING.md，比口头强调管用
配置变更别用 git revert，优先 git cherry-pick
git revert 会产生反向提交，在 ThinkPHP 里容易破坏配置加载顺序。比如某次 revert 把中间件注册逻辑倒着执行一遍，结果路由没注册、Auth 中间件却先跑了。
- 线上紧急修复配置（如数据库密码、Redis 地址），应该从 hotfix 分支
cherry-pick到main，而不是 revert 旧提交 - 所有环境配置统一走
.env（忽略）+.env.example（提交），新人cp .env.example .env后填值 -
composer.lock必须提交——它才是依赖版本的唯一权威，vendor/绝对不能进仓库
最常被跳过的其实是 php think clear 和分支名校验。前者导致回滚后页面白屏还查半天代码，后者让三个人同时在“看似同一个分支”上改不同东西——问题不在 Git，而在 ThinkPHP 的缓存机制和团队对分支语义的默认理解偏差。
