大型PHP项目必须采用「环境分支+功能分支」双轨制：main仅接收已验证发布、staging严格对应预发部署、develop为集成基线，所有功能从develop拉出feature分支并经PR合并；composer.lock必须提交且精确锁定所有依赖版本；数据库迁移须与代码同提交、含时间戳、仅用框架Schema构建器、确保幂等；配置须完全剥离代码，由运行时环境注入，禁止明文敏感信息入Git。
Git 分支策略必须按环境+功能分层
大型 PHP 项目一旦多人并行开发，直接在 main 上提交等于埋雷。推荐采用「环境分支 + 功能分支」双轨制：main（仅接受已验证的发布版本）、staging（预发环境对应）、develop（日常集成基线），所有新功能必须从 develop 拉出 feature/xxx 分支，完成后再以 Pull Request 合并回 develop。
常见错误是把 staging 当作“测试分支”随意合入——它应严格对应预发服务器部署状态，每次合入前必须跑通 CI 中的完整测试套件（含数据库迁移校验）。另外，禁止直接 push 到 main 或 staging，必须通过保护分支规则强制 Code Review。
-
git checkout -b feature/user-auth-jwt develop—— 功能分支永远基于develop而非main - 合并前执行
git rebase develop消除冗余分叉，避免 merge commit 污染历史 - PHP 项目常带
composer.lock，该文件必须提交，且每次composer update后需重新 commit
Composer 依赖版本锁定要精确到 patch 级
大型 PHP 项目依赖链深，composer.json 里写 "monolog/monolog": "^2.0" 看似稳妥，实则危险：某次 composer update 可能拉入 2.10.0，而其中某个 patch 版本（如 2.8.2）悄悄改了日志上下文序列化逻辑，导致审计模块报错。生产环境必须用 composer.lock 锁死全部依赖的 exact version（包括子依赖）。
团队协作时容易忽略的是 lock 文件的更新节奏。CI 流程中应在每次构建前运行 composer install --no-dev（而非 update），确保部署包与本地开发一致；开发者本地升级依赖时，必须先在 develop 分支上完成测试，再提交更新后的 composer.lock。
立即学习“PHP免费学习笔记（深入）”；
- 检查 lock 文件是否过期：运行
composer outdated --direct查看直连依赖变更 - 禁止在
main或staging分支上执行composer update，只允许在feature分支中操作 - 若使用私有 Packagist，确保
auth.json不进 Git，通过 CI secrets 注入
数据库迁移必须和代码版本强绑定
PHP 项目里最隐蔽的不一致来源就是数据库结构。不能靠 DBA 手动执行 SQL，也不能依赖“上线时跑一遍 migration 脚本”的模糊流程。Laravel 的 php artisan migrate 或 Doctrine Migrations 都行，关键是：每个 migration 文件名必须含时间戳（如 20230512142300_add_user_status_column.php），且该文件必须和对应功能代码一起提交、一起评审、一起发布。
常见坑是 migration 中写了 DB::statement() 执行原生 SQL，却没考虑 MySQL 和 PostgreSQL 的语法差异；或在 up() 里加了索引但没在 down() 中删掉，导致回滚失败。更严重的是，在 migration 里调用业务模型（如 User::create()），一旦模型后续重构，旧 migration 就无法重放。
- 迁移文件只能用框架提供的 Schema 构建器（如
$table->string('email')），禁用原生 SQL 除非明确标注兼容性 - 所有 migration 必须可重复执行（idempotent）：用
Schema::hasTable()或Schema::hasColumn()做前置判断 - 上线前在 staging 环境执行
php artisan migrate --pretend预览 SQL，确认无 DDL 风险
配置管理必须剥离代码，按环境动态加载
把 DB_HOST、API_KEY 写死在 .env 或配置数组里，是大型 PHP 项目最常被扫描出的漏洞点。正确做法是：代码中只保留配置键名（如 getenv('DB_PASSWORD')），真实值由部署环境注入。Docker 使用 --env-file，K8s 用 Secret 挂载，PHP-FPM 容器启动时通过 env[DB_PASSWORD] 透传。
很多人以为用 vlucas/phpdotenv 加载 .env 就算解耦了，其实不然——.env 本身仍是代码库一部分，极易误提交。真正安全的路径是：CI 构建阶段不加载任何敏感配置，镜像保持纯净；运行时由基础设施注入，且不同环境（dev/staging/prod）注入不同值。
- 禁止在 Git 中出现
.env、config/database.php里含明文密码的文件 - 使用
$_ENV而非getenv()（后者在某些 SAPI 下不可靠） - 配置项命名统一加前缀，如
APP_ENV、DB_CONNECTION，避免与系统变量冲突
QUEUE_TIMEOUT，但没同步更新 deployment manifest，结果线上服务读不到默认值而崩溃。这类问题不会出现在单元测试里，只能靠部署检查清单（checklist）和环境一致性比对工具来兜底。 
