Composer 的 scripts 是声明式钩子注册机制，而非运行脚本的工具；它通过键值对将事件名（如 post-install-cmd）映射到预定义命令，在生命周期触发执行，不改变 Composer 自身流程。
Composer 的 scripts 不是“运行脚本的工具”，而是对已存在命令的**声明式钩子注册机制**——它本身不执行逻辑，只在特定生命周期触发预定义命令。
scripts 是什么：不是 shell 脚本，而是事件钩子映射表
Composer 的 scripts 段本质是一组键值对，key 是事件名（如 post-install-cmd），value 是要执行的命令字符串或数组。这些命令在 Composer 执行对应操作后自动调用，但不会改变 Composer 自身行为流程。
- 所有 script 命令默认在项目根目录下执行，
cwd不可配置（除非用symfony/process手动切路径） - 不支持直接写多行 shell 逻辑（如
if、for），必须封装成独立可执行文件或使用&&连接简单命令 - script 中的
$COMPOSER_HOME、$PWD等环境变量可用，但$0不指向当前 script 文件（因为根本没“脚本文件”）
常见内置事件与典型用途
Composer 内置约 20 个事件，高频使用的有：
-
pre-install-cmd：安装前校验依赖是否满足（如检查 PHP 版本） -
post-install-cmd：安装后生成 autoload、清理缓存、初始化配置文件 -
post-update-cmd：更新后重新生成 classmap 或触发 CI 风格检查 -
post-autoload-dump：每次composer dump-autoload后自动刷新代理类或注解缓存
注意：post-autoload-dump 在 install 和 update 中都会触发，但不会在 require 单个包时单独触发（除非该操作导致 autoloader 变更）。
如何定义可复用的自定义脚本命令
把复杂逻辑抽离为独立 PHP 类方法或 CLI 工具，再通过 scripts 引用，是最可靠的做法。例如：
{
"scripts": {
"check-env": [
"@php -r \"if (!extension_loaded('pdo')) { exit(1); }\"",
"MyApp\\Scripts\\EnvChecker::run"
],
"post-install-cmd": [
"@php bin/console cache:clear --env=prod",
"@check-env"
]
}
}
- 以
@开头表示调用另一个 script（支持嵌套） - 类方法引用格式为
Namespace\\Class::method，该类需能被 Composer 自动加载（即在autoload中声明） - 不推荐直接写长 shell 命令（如
find ./src -name '*.php' | xargs php -l），因 Windows 下会失败且不可调试
调试 scripts 执行失败的关键点
scripts 报错时 Composer 默认只显示退出码，很难定位问题。实际排查需关注：
- 错误信息里是否含
Script ... handling the ... event returned with error code 1？说明命令返回非零退出码，但具体哪一行失败需加-v参数重试 - 执行
composer run-script post-install-cmd -v可看到每条命令的完整输出和工作路径 - PHP 类方法若抛异常，Composer 会捕获并转为 exit(1)，但堆栈不会打印——务必在方法内加
try/catch并显式echo错误 - Windows 用户要注意：用
cmd解析的命令中反斜杠\需双写，或统一改用/路径分隔符
真正麻烦的从来不是怎么写 script，而是当多个 package 都注册了同一个事件（比如十几个包都写了 post-autoload-dump），执行顺序由 composer.json 声明顺序决定，且无法干预——这点很容易被忽略。
