PHP 项目版本控制与多环境配置管理-php教程-PHP中文网

php项目稳定交付需闭环管理：提交composer.lock锁定依赖、.env.example定义配置契约、.php-version固定php版本、迁移文件带时间戳且幂等，四者缺一不可。

php 项目版本控制与多环境配置管理

PHP 项目要稳定交付，必须把版本控制和多环境配置当成同一套问题来解：代码改了但数据库迁移没跑，是版本失控；本地能跑生产报错，是配置没对齐。两者不联动，CI/CD 就是纸老虎。

composer.lock 必须提交，且只在 feature 分支更新

大型 PHP 项目依赖链深，composer.json 里写 "monolog/monolog": "^2.0" 看似宽松，实际某次 composer update 可能拉入 2.10.0，而其中 2.8.2 已悄悄破坏日志上下文序列化逻辑——这种 patch 级别差异在生产环境会直接导致审计模块静默失败。

composer.lock 是部署事实依据，必须提交到 Git，且精确锁定所有依赖（含子依赖）的 exact version
禁止在 main 或 staging 分支执行 composer update，只允许在 feature/xxx 分支中操作并完成全量测试后合并
CI 流程中必须用 composer install --no-dev（而非 update），确保构建产物与开发环境一致
检查 lock 是否过期：运行 composer outdated --direct 查看直连依赖变更

.env 文件不进 Git，但 .env.example 必须进

硬编码数据库密码、API 密钥到代码或配置文件，等于把钥匙挂在门上。敏感信息必须剥离版本控制，靠运行时注入。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

.env 文件必须加入 .gitignore，绝不可提交；它只存在于具体部署节点（本地开发机、测试服务器、生产容器）
.env.example 必须提交，内容为完整字段+注释+占位值（如 DB_PASS=your_password_here），新成员克隆后复制重命名为 .env 并填值
推荐使用 vlucas/phpdotenv 加载：$dotenv = Dotenv\Dotenv::createImmutable(__DIR__); $dotenv->load();
生产环境不走 .env，而是由 CI/CD secrets 注入环境变量，或通过 Docker 的 environment: 配置项传递

phpenv local 实现项目级 PHP 版本隔离

一个团队同时维护 PHP 7.4 的遗留系统和 PHP 8.2 的新服务？全局切换版本只会让协作雪上加霜。项目级绑定才是解法。

进入项目 A 目录执行 phpenv local 7.4.33，自动生成 .php-version 文件，该目录下所有 php 命令自动指向 7.4.33
进入项目 B 目录执行 phpenv local 8.2.0，同样生成对应 .php-version，互不干扰
.php-version 文件应提交到 Git，保证团队成员 clone 后无需手动设置，环境开箱即用
避免用 phpenv global 覆盖系统默认，它会污染其他非 phpenv 管理的脚本或工具链

数据库迁移必须带时间戳、幂等、随代码提交

“上线前 DBA 手动跑 SQL” 或 “部署脚本里 echo 一句‘请手动执行 migration’”，都是埋雷。结构变更必须和代码版本强绑定，否则回滚即灾难。

所有 migration 文件名必须含时间戳前缀（如 20260512143000_add_user_status_column.php），确保顺序可追溯
迁移逻辑必须幂等：重复执行不能报错，可用 if (!Schema::hasColumn(...)) 或 DB::statement('CREATE TABLE IF NOT EXISTS ...')
migration 文件随功能代码一起提交，合入 develop 前必须在本地和 CI 中验证：先 php artisan migrate，再 php artisan migrate:rollback 成功
禁止在 migration 中调用业务模型或外部服务——它只负责 DDL/DML，不承担领域逻辑

真正难的不是写对某一行配置或记住某个命令，而是让所有环节形成闭环：composer.lock 锁死依赖 → .env.example 定义契约 → .php-version 固定解析器 → migration 文件绑定结构变更。漏掉任何一环，环境一致性就变成概率事件。