Composer怎么配置scripts钩子_Composer脚本命令编写规范【核心】

Composer脚本命令编写规范：避开那些“静默失效”的坑

想把自动化脚本写进composer.json？这事儿看似简单，实则处处是“暗礁”。一个字母拼错，或者引号没加对，你的脚本就可能彻底“静默失效”——不是报错提醒你，而是直接当作不存在，悄无声息地罢工。

scripts 必须放在 composer.json 顶层，不能嵌套

首先得明确一点：scripts可不是什么config或extra的“下属部门”。它和name、require一样，是根级别的“合伙人”。放错了位置，一切努力都白费。

下面这两种常见的错误写法，你中招了吗？

• "extra": { "scripts": { "dev:serve": "php -S localhost:8000" } } → 脚本不会生效。
• "config": { "scripts": { ... } } → 配置会被完全忽略。

正确的结构有且只有一种，那就是让它“站对位置”：

{
  "name": "my/app",
  "require": { ... },
  "scripts": {
    "dev:serve": "php -S localhost:8000",
    "post-install-cmd": ["@php scripts/init.php"]
  }
}

另外，JSON的语法规则必须遵守：键名和字符串值都必须用双引号包裹。如果把"dev:serve"写成dev:serve（没有引号）或者用单引号，解析器就会直接“罢工”。

钩子名别写错：post-install-cmd 和 post-update-cmd 触发时机完全不同

这两个名字长得像，但触发逻辑天差地别，混用它们可能会让你的CI/CD流程变得不可靠：

• post-install-cmd：只在vendor/目录为空时运行（通常是首次执行composer install）。之后再次运行install，它就不会被触发了。
• post-update-cmd：每次执行composer update或composer install --with-dependencies时，它都会执行。

举个例子，如果你在CI环境中把清理缓存的操作写在了post-install-cmd里，那么当依赖更新后，旧的缓存就可能残留下来，导致构建行为不一致。更稳妥的做法是把这类清理操作统一放到post-update-cmd中，或者在必要时手动执行composer run-script post-update-cmd来补救。

命令怎么写：字符串 vs 数组 vs PHP 回调

定义脚本命令有三种方式，用错了场景，路径、环境、参数问题就会接踵而至：

• 单条shell命令用字符串："test": "vendor/bin/phpunit"。这里有个细节：别直接写phpunit，因为系统的PATH环境变量不一定包含全局命令。
• 多条命令优先用数组："pre-start": ["@php -v", "npm run build"]。这样做可以避免shell解析的差异，比如在Windows系统下，&&操作符可能不被识别。
• PHP回调要确保自动加载就绪："build:config": ["App\Scripts\ConfigBuilder::run"]。这里引用的类必须已经通过autoload配置注册，否则会直接报错：Class 'App\Scripts\ConfigBuilder' not found。

另外，在数组写法中，以@开头的项（比如@php）会被Composer递归解析，它会自动使用当前项目绑定的PHP版本，这比硬编码php命令要安全得多。

传参和调试：-- 是分隔符，$argv 不可靠

给脚本传递参数时，--这个分隔符至关重要。Composer本身不解析参数，--之后的内容才会原封不动地传递给底层命令。漏掉它，参数就“丢在半路”了：

• ✅ 正确写法：composer test:unit -- --filter=testLogin
• ❌ 错误写法：composer test:unit --filter=testLogin → phpunit根本收不到--filter参数。

在PHP脚本内部，也别依赖$argv来获取参数，因为它的索引很容易发生偏移。更推荐的做法是读取$_SERVER['COMPOSER_ARGS']（Composer 4.0及以上版本提供），它直接就是--后面的参数数组。

调试脚本时，可以加上-v参数来查看Composer实际执行的命令。或者在脚本里临时插入echo语句来打点，比如：

"post-install-cmd": ["echo '>> vendor built'", "@php scripts/check-env.php"]

最后，还有两个容易被忽略的“环境陷阱”：Composer执行脚本时，当前工作目录确实是项目根目录，但$PATH环境变量里并不包含vendor/bin目录，同时.env文件也不会被自动加载——这些环境问题，都需要在你的脚本里自行处理妥当。