post-install-cmd仅在vendor/不存在或为空、composer.lock缺失或与composer.json不匹配、且未加--no-scripts时才执行；必须配置在composer.json顶层scripts下，键名严格为"post-install-cmd"，否则静默失效。
post-install-cmd 什么时候会真正执行
它只在三种条件同时满足时触发：项目根目录下 vendor/ 不存在或为空；composer.lock 缺失，或内容与 composer.json 中声明的依赖不一致；命令未加 --no-scripts。本地反复运行 composer install 却没反应？大概率是 vendor/ 已存在，Composer 直接跳过初始化流程，此时脚本根本不会跑。
脚本必须写在 composer.json 的哪个位置
scripts 字段必须位于 composer.json 顶层，和 require、autoload 同级。写进 extra、缩进错位、漏掉 s（写成 script）或键名拼错（如 post_install_cmd、PostInstallCmd），都会被 Composer 静默忽略——不报错，也不执行。
键名必须严格为 post-install-cmd（注意后缀 -cmd），值可以是字符串、字符串数组或关联数组：
"scripts": {
"post-install-cmd": [
"php scripts/install.php",
"chmod 755 ${PWD}/storage"
]
}PHP 脚本里 new 类为什么报 Class not found
Composer 执行 post-install-cmd 时，vendor/autoload.php 可能尚未完全就绪，且默认不自动加载项目类。这不是配置漏了，而是执行时机导致的隔离行为。
立即学习“PHP免费学习笔记（深入）”；
- 在 PHP 脚本第一行显式写：
require __DIR__ . '/vendor/autoload.php';（注意：脚本若放在scripts/目录下，__DIR__指向该目录，所以路径是/vendor/autoload.php，不是../vendor/autoload.php） - 确保类已声明在
autoload或autoload-dev中，并已运行过composer dump-autoload - 方法必须是
public static；避免直接new尚未通过 autoload 注册的第三方类（如new Illuminate\Support\Str）
参数和权限问题最容易踩坑
post-install-cmd 不支持传参——它不是手动触发的 composer run-script，没有 -- 分隔机制。所有逻辑必须硬编码或通过环境变量判断（如 getenv('COMPOSER_DEV_MODE')）。
部署机上常见失败原因：
- 脚本运行用户 ≠ Web 服务器用户，
storage/权限不一致 → 报Permission denied - 用裸
chmod、chown命令 → Windows 上直接失败 - 写相对路径如
cp .env.example .env→ 实际工作目录是项目根，但 CI 环境可能从子目录触发命令，路径失效
更稳妥的做法：把需要参数或跨平台兼容的操作，拆成独立脚本名（如 deploy:setup），用 composer run-script deploy:setup -- --env=prod 显式调用；post-install-cmd 只做最基础、无参、确定性高的动作。
