post-root-package-install 脚本在首次 composer install 且 vendor/ 为空时触发，用于一次性初始化（如复制 .env、生成密钥），仅作用于根包，需在 composer.json scripts 中配置，推荐封装为独立 PHP 脚本并用原生函数确保兼容性。
在 Composer 的 composer.json 中配置 post-root-package-install 脚本，可以在项目首次安装（即执行 composer install 且 vendor/ 为空时）自动运行初始化逻辑，比如生成配置文件、创建目录、设置环境变量等。它只对根包（即当前项目本身）生效，不适用于依赖包。
理解 post-root-package-install 的触发时机
该事件仅在以下情况触发一次：
- 当前目录是 Composer 项目的根目录（含
composer.json） -
vendor/目录不存在或为空 - 执行的是
composer install（不是update或require）
注意：它不会在 composer update 或后续 install 中重复执行，适合做一次性初始化任务。
在 composer.json 中定义脚本
在根项目的 composer.json 的 "scripts" 段中添加：
"scripts": {
"post-root-package-install": [
"php -r \"copy('.env.example', '.env');\"",
"php artisan key:generate"
]
}
上面示例适用于 Laravel 项目：先复制环境配置模板，再生成应用密钥。你也可以指向自定义 PHP 文件：
"post-root-package-install": [ "@php init/init-project.php" ]
确保 init/init-project.php 具有可执行权限（如需），且路径相对于项目根目录。
编写可复用的初始化脚本
推荐将逻辑封装为独立 PHP 脚本，便于测试和维护。例如 scripts/init.php：
<?php
// scripts/init.php
if (!file_exists('.env')) {
copy('.env.example', '.env');
echo "✓ Copied .env.example to .env\n";
}
if (!file_exists('storage/logs')) {
mkdir('storage/logs', 0755, true);
echo "✓ Created storage/logs directory\n";
}
echo "Project initialized.\n";
然后在 composer.json 中调用：
"post-root-package-install": [ "php scripts/init.php" ]
调试与验证技巧
若脚本未执行，检查以下几点：
- 确认命令行在项目根目录下运行
composer install - 删除
vendor/和composer.lock后重试（模拟首次安装） - 使用
composer install -v查看详细日志，确认事件是否被触发 - 脚本中加入
echo或file_put_contents('debug.log', ...)辅助定位问题
避免在脚本中依赖尚未安装的第三方类——此时 vendor/autoload.php 可能还未生成，建议只用原生 PHP 函数或明确保证可用的工具（如 php CLI 自带命令）。
