Composer如何运行自定义脚本_在composer.json配置scripts【开发利器】

自定义脚本不会自动运行，必须通过 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 参数来查看实际的退出码。