post-install-cmd仅在vendor不存在或为空、composer.lock缺失或与composer.json不匹配、且未加--no-scripts时触发;必须严格配置为顶层scripts下的"post-install-cmd"数组,否则静默失效。

post-install-cmd 不会每次 composer install 都执行,它只在 vendor 目录真正从零创建时触发——你配对了、写对了、路径也没错,但脚本就是不跑,大概率是触发条件根本没满足。
post-install-cmd 什么时候才真会执行
它不是“只要敲了 install 就跑”,而是严格依赖三件事同时成立:
- 项目根目录下
vendor/不存在,或存在但为空 -
composer.lock不存在,或内容与composer.json中的require/require-dev不匹配(比如你改了依赖却没composer update) - 没加
--no-scripts参数(CI 环境默认常带这个)
常见误判:本地反复运行 composer install,vendor/ 一直存在 → Composer 直接跳过安装流程,post-install-cmd 完全不会被调用。此时应删掉 vendor/ 和 composer.lock 后重试,或改用 post-update-cmd。
composer.json 里怎么写才有效
必须满足四个硬性条件,缺一不可:
- 整个
"scripts"块必须在composer.json的**顶层**,不能嵌套在autoload、extra或其他字段里 - 键名必须严格为
"post-install-cmd"(全小写、短横线、cmd结尾,不是post-install、PostInstall或post_install_cmd) - 值必须是数组(推荐)或字符串;JSON 中不能有注释,否则解析失败
- 命令中若含空格或特殊字符(如
php artisan migrate --force),整条命令需用双引号包裹
最小可用示例:
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
{
"scripts": {
"post-install-cmd": [
"@php -r "echo '✅ Installed\n';"",
"php artisan key:generate",
"chmod -R 755 storage bootstrap/cache"
]
}
}
脚本里调用 PHP 文件为什么总报错
路径错误是最常见的失败原因,尤其在跨平台或 Docker 环境中:
- Composer 执行脚本时工作目录始终是项目根目录,所以
php scripts/deploy.php是安全的,而php ./scripts/deploy.php更稳妥(显式声明相对路径) - 别在被调用的 PHP 脚本里依赖
__DIR__推导路径——因为 Composer 是用proc_open新启进程执行的,__DIR__指向的是 PHP 解释器所在位置,不是你的脚本目录 - 如果脚本需要加载 Composer 自动加载机制(例如要用到
AppSomeClass),开头必须手动引入:require __DIR__ . '/vendor/autoload.php'; - Windows 下避免硬写反斜杠
,用DIRECTORY_SEPARATOR或正斜杠/更可靠
为什么 CI 里脚本完全没反应
CI/CD 流水线(GitHub Actions、GitLab CI、Laravel Forge 等)默认往往加了 --no-scripts,这是最常被忽略的点:
- 检查构建命令是否为
composer install --no-interaction --no-scripts,去掉--no-scripts或显式加上--scripts - 如果用了
npm install这类外部命令,确认 CI 镜像中已预装 Node.js,且npm在PATH中 - PHP 脚本权限问题在 Linux 容器里很隐蔽:用
php -f script.php替代./script.php,避免因缺少执行权限导致Permission denied - 脚本失败会中断整个
composer install流程(退出码非 0),建议关键步骤后加|| true(如cp .env.example .env || true)防止阻断,但仅限非关键操作
真正容易被忽略的,是把 post-install-cmd 当成“每次 install 都该跑”的通用钩子——它本质是一次性初始化机制,不是常规调度器。需要稳定触发的逻辑,得靠 post-update-cmd 或 post-autoload-dump 补位。










