自定义脚本不会自动运行，必须通过 composer run 或生命周期钩子（如 post-install-cmd）触发；写进 composer.json 的 scripts 字段只是声明，不是注册命令。
这里有个核心结论需要先明确： 在 composer.json 里写好脚本，并不意味着它就会自己跑起来。这些脚本声明，必须通过 composer run 命令手动调用，或者绑定到特定的生命周期事件（比如 post-install-cmd）上，才会被触发执行。
脚本名怎么写、怎么调用才有效
脚本的命名和调用，其实是个“对暗号”的过程。你定义的键名就是命令名，它大小写敏感，不能包含空格，而且必须和 composer run 后面跟的名字完全一致。举个例子：
"scripts": {
"dev:setup": "php scripts/setup.php",
"post-update-cmd": ["My\Script::clearCache"]
}
那么，对应的调用方式就是：
composer run "dev:setup"（注意双引号，在 Windows 环境下是必须加的）- 或者用
composer run-script "post-update-cmd"（不过更推荐统一的composer run） - 当然，直接执行
composer update也会自动触发绑定的post-update-cmd钩子
脚本“失效”的常见原因，往往就出在这些细节上：
- 脚本名拼写不一致，比如定义的是
dev-setup，调用时却用了composer run dev_setup。 - 在 Windows 系统下调用带冒号的脚本时，忘了加引号，导致命令报错或者静默失败。
scripts字段的缩进位置放错了，比如不小心嵌套到了require或其他配置块里，导致 Composer 根本读取不到。
PHP 回调脚本为什么报 Class not found
当你使用 MyScript::method 这种 PHP 回调写法时，可能会遇到“类找不到”的错误。这通常不是因为配置漏了，而是因为 Composer 在执行这类脚本时，并不会自动加载项目的 autoloader。
要解决这个问题，必须确保两点：
- 首先，这个类确实已经声明在
autoload或autoload-dev配置中，并且执行过composer dump-autoload来生成最新的加载映射。 - 其次，被调用的方法必须是
public static的，并且参数签名要兼容（可以接收一个可选的$event对象）。
最稳妥的做法，是在 PHP 脚本的开头就显式引入 Composer 的自动加载文件：
require __DIR__ . '/vendor/autoload.php';
记住，不要依赖 __autoload 函数或者手动去 include 单个文件——那样很容易遗漏依赖，也绕不开 Composer 自身的自动加载机制。
传参和跨平台执行要注意什么
如果想给脚本传递参数，比如把 --filter=TestFoo 传给 PHPUnit，就必须用 -- 进行显式分隔：
- ✅ 正确写法：
composer run test -- --filter=TestFoo - ❌ 错误写法：
composer run test --filter=TestFoo（这样参数会被 Composer 自身拦截掉）
脚本内容本身也需要考虑跨平台的兼容性：
- 对于 Shell 命令，建议使用数组格式来写，比如
["vendor/bin/phpunit", "--testsuite=unit"]。这样可以避免因空格和引号解析带来的各种奇怪问题。 - 在 Windows 下，不要硬编码
php.exe这样的路径，直接用@php或者简单的php，Composer 会帮你处理好。 - 路径一律使用相对路径，比如
./vendor/bin/phpcs，不要只写phpcs（依赖系统的 PATH 环境变量并不可靠）。
另外需要注意，父进程的环境变量（如 $PATH）默认不会被继承，项目根目录下的 .env 文件也不会自动加载，这些都需要在脚本内部手动处理。
钩子脚本该放哪、什么时候跑
post-install-cmd 和 post-update-cmd 这两个钩子，并不是“安装完”或“更新完”就一定会跑。它们严格绑定在具体的命令上：
- 执行
composer install时，会触发post-install-cmd。 - 执行
composer update或者composer require xxx时，只会触发post-update-cmd，而不会触发post-install-cmd。 - 如果是与自动加载相关的操作，比如刷新缓存、生成类映射文件，优先考虑使用
post-autoload-dump钩子。它触发得更精准，行为也更稳定。
当多个脚本需要共用一个钩子时，使用数组写法：
"post-autoload-dump": [ "My\Cache::clear", "php artisan config:clear" ]
这里有个容易被忽略的细节：如果数组中的某个脚本执行后返回了非零的退出码，那么同在这个钩子里的后续脚本都会被跳过。调试时，可以加上 -v 参数来查看实际的退出码。
