post-install-cmd 是 Composer 的脚本钩子，仅在首次执行 composer install（vendor/ 不存在或为空）时触发，用于一次性初始化操作如生成密钥、设置权限；需在 composer.json 的 scripts 中配置，不适用于已有依赖的更新场景。
post-install-cmd 是什么，什么时候会触发
post-install-cmd 是 Composer 提供的脚本事件钩子，**仅在执行 composer install 且项目中尚无 vendor/ 目录（或该目录为空）时触发**。它不会在 composer update 或已有依赖已安装的情况下运行——这点常被误认为“每次 install 都执行”，实际只对首次安装生效。
典型场景：初始化新项目、CI/CD 流水线拉取代码后首次构建、Docker 构建阶段安装依赖并生成缓存/配置文件。
如何在 composer.json 中配置 post-install-cmd
在 composer.json 的 "scripts" 字段下添加键值对即可：
{
"scripts": {
"post-install-cmd": [
"@php artisan key:generate",
"chmod -R 755 storage bootstrap/cache"
]
}
}
注意几点：
- 值可以是字符串（单条命令）或字符串数组（多条顺序执行）
- 数组内支持以
@开头的内置脚本别名，如@php、@composer，它们会自动解析为当前环境的可执行路径 - 每条命令独立执行，失败会中断后续；若需忽略某条失败，可用
|| true（如cp .env.example .env || true） - 不建议在其中写长逻辑，应封装为独立 PHP 脚本再调用，便于测试和复用
常见错误：为什么 post-install-cmd 没有执行
最常遇到的不是配置错，而是触发条件不满足：
-
vendor/已存在且非空 → Composer 认为“已安装”，跳过post-install-cmd，改走post-update-cmd - 用了
composer install --no-scripts→ 所有脚本都被禁用 - 脚本中调用的命令不在 PATH 中（比如
artisan未加./前缀，或未设可执行权限）→ 报sh: artisan: not found - PHP 版本不匹配导致脚本解析失败（如用了高版本语法但容器里是 PHP 7.4）→ 错误可能静默吞掉，建议加
echo "running..."排查
与 post-update-cmd 的关键区别和选型建议
post-install-cmd 和 post-update-cmd 不是互斥替代关系，而是分工明确：
-
post-install-cmd：适合一次性初始化操作，比如生成密钥、创建软链、初始化数据库结构模板 -
post-update-cmd：适合每次依赖变更都需同步的动作，比如更新 Swagger 文档、重建 Laravel Telescope 数据表、刷新包的 autoload 映射 - 若想“无论 install 还是 update 都执行”，得同时配置两个钩子，或统一写进
post-autoload-dump（它在 autoloader 重建后触发，更稳定）
真正容易被忽略的是：很多团队把部署脚本全堆在 post-install-cmd 里，结果上线时因 vendor 已存在而漏执行——这时得靠 CI 显式加 rm -rf vendor && composer install，或者换用更可靠的钩子时机。
