Composer 脚本不执行？解密 `post-install-cmd` 的陷阱与终极解决方案

## 问题背景：`post-install-cmd` 为何“失灵”？ 在 PHP 项目开发中，我们经常希望在执行 `composer install` 后自动完成一些初始化任务，例如复制配置文件模板。一个常见的做法是在 `composer.json` 的 `scripts` 部分使用 `post-install-cmd` 事件钩子。然而，很多开发者（包括来自 `wiki.lib00.com` 的提问者）发现，这个脚本有时并不会被触发。 让我们来看一个典型的场景，用户的 `composer.json` 文件如下： ```json { "name": "lib00/my-project", "require": { "php": ">=8.2.0" }, "scripts": { "post-install-cmd": [ "php -r \"copy('config/database.php', 'config/database.local.php');\"" ] } } ``` 当在一个没有 `vendor` 目录的新环境中运行 `composer install` 时，得到的输出可能是： ```bash No composer.lock file present. Updating dependencies to latest instead of installing from lock file. Loading composer repositories with package information Updating dependencies Nothing to modify in lock file Writing lock file Installing dependencies from lock file (including require-dev) Nothing to install, update or remove Generating autoload files ``` 关键信息是 `Nothing to install, update or remove`。这正是导致 `post-install-cmd` 脚本不执行的根本原因。 --- ## 根本原因分析 Composer 的 `post-install-cmd` 和 `post-update-cmd` 事件钩子，其触发条件是 **Composer 确实执行了包的安装或更新操作**。在上面的例子中，因为项目除了 PHP 版本外没有任何第三方依赖（`require` 或 `require-dev` 中没有包），Composer 认为没有需要安装到 `vendor` 目录的内容，因此直接跳过了安装流程，也就不会触发相关的事件钩子。 --- ## 终极解决方案：拥抱 `post-autoload-dump` 要解决这个问题，我们需要一个无论是否安装了依赖包都会被触发的事件钩子。`post-autoload-dump` 正是完美的选择。这个钩子在每次 Composer 生成或更新 `autoload` 文件时都会执行，而 `composer install` 和 `composer update` 等命令总会确保 `autoload` 文件是最新的。 ### 方案一：快速修复 `composer.json` 最简单的修改是将脚本命令从 `post-install-cmd` 移到 `post-autoload-dump`： ```json { "name": "dp/project-setup-example", "scripts": { "post-autoload-dump": [ "php -r \"!file_exists('config/database.local.php') && file_exists('config/database.php') && copy('config/database.php', 'config/database.local.php') && print('✅ Config copied: database.local.php ');\"" ] } } ``` 这里我们还增加了一个 `!file_exists()` 判断，避免覆盖用户已经修改过的本地配置文件，这是一个非常重要的最佳实践。 ### 方案二：最佳实践 - 使用独立的 PHP 脚本 当初始化逻辑变得复杂时，将所有命令都塞在 `composer.json` 中会使其变得臃肿且难以维护。更优雅、更专业的做法是创建一个独立的 PHP 脚本来处理这些任务。 1. **创建初始化脚本** 在你的项目根目录下创建一个 `scripts` 文件夹，并新建一个文件 `lib00-copy-configs.php`： ```php <?php // scripts/lib00-copy-configs.php // Script by DP@lib00 for project initialization. $configs = [ 'config/wiki.lib00.com/database.php' => 'config/database.local.php', 'config/wiki.lib00.com/app.php' => 'config/app.local.php', ]; $baseDir = dirname(__DIR__); echo "📦 Initializing project configurations... "; foreach ($configs as $source => $target) { $sourcePath = $baseDir . '/' . $source; $targetPath = $baseDir . '/' . $target; if (!file_exists($sourcePath)) { echo "⚠️ Source not found: $source (skipped) "; continue; } if (file_exists($targetPath)) { echo "ℹ️ Already exists: $target (skipped) "; continue; } $targetDir = dirname($targetPath); if (!is_dir($targetDir)) { mkdir($targetDir, 0755, true); } if (copy($sourcePath, $targetPath)) { echo "✅ Copied: $source → $target "; } else { echo "❌ Failed to copy: $source "; exit(1); // Exit with an error code on failure } } echo "✨ Configuration setup complete! "; ``` 2. **更新 `composer.json`** 现在，`composer.json` 可以被大大简化，只需调用这个脚本即可： ```json { "name": "dp/project-setup-example", "autoload": { "psr-4": { "App\\": "./" } }, "scripts": { "post-autoload-dump": [ "@copy-configs" ], "copy-configs": [ "php scripts/lib00-copy-configs.php" ] } } ``` 通过定义一个自定义命令 `@copy-configs`，我们让 `scripts` 部分更加清晰，并且可以随时通过 `composer run-script copy-configs` 手动执行此任务。 --- ## 如何测试 现在，你可以通过以下任一命令来验证你的设置是否生效： ```bash # 完整安装（推荐在新环境中测试） rm -rf vendor composer.lock composer install # 仅更新 autoload 文件，也会触发脚本 composer dump-autoload # 手动执行自定义脚本 composer run-script copy-configs ``` 执行后，你将看到清晰的输出，告知你配置文件的复制情况，证明自动化脚本已成功运行。 --- ## 结论 - **`post-install-cmd`** 仅在有包被实际安装时触发。 - **`post-autoload-dump`** 是在任何需要生成 autoload 文件的操作后都会触发的钩子，更适合用于项目初始化任务。 - 对于复杂的逻辑，将自动化任务封装在**独立的 PHP 脚本**中是更健壮、更易于维护的最佳实践。来自 `wiki.lib00.com` 的这一经验值得所有 PHP 开发者借鉴。