Composer Scripts 不支持异步、条件分支或复杂逻辑，应将逻辑移至独立 PHP/Shell 脚本中封装并调用；因其仅做 shell 级串联，不解析 if/else 等语法，且跨平台 shell 环境不可控、变量展开不可靠，故需用外部脚本实现可测试、易调试的构建流程。
Composer Scripts 本身不支持异步、条件分支或复杂逻辑，直接在 composer.json 里写多步骤构建任务会迅速失控——真正可行的做法是把逻辑移出 JSON，用独立脚本封装，再通过 Composer 调用。
为什么不能在 scripts 字段里写 if/else 或循环
Composer 的 scripts 是纯命令列表，执行机制是 shell 级串联（&&）或简单调用，不解析语法结构。写成这样会失败：
"post-install-cmd": "if [ \"$COMPOSER_DEV_MODE\" = \"1\" ]; then npm install; fi"
原因：Composer 会把整条字符串传给 PHP 的 proc_open()，而默认 shell 环境不可靠（Windows 上是 cmd，Linux/macOS 可能是 sh 而非 bash），且变量展开由宿主 shell 控制，不可控。
- 跨平台脚本必须避免
[[ ]]、$(( ))、数组等 bash 特有语法 -
composer.json中的$符号会被 Composer 自身提前解析（如$HOME），导致变量名被清空或误替换 - 错误不会中断后续命令，除非显式加
&&，但又无法捕获退出码做分支
用独立 PHP/Shell 脚本替代内联命令
把判断、循环、日志、重试等逻辑放进可测试的外部文件，Composer 只负责触发。这是最稳定、可调试、易协作的方式。
- PHP 脚本放在
bin/build.php，用#!/usr/bin/env php开头，加可执行权限：chmod +x bin/build.php - Shell 脚本放在
bin/deploy.sh，第一行写#!/bin/sh（不用 bash，保证 POSIX 兼容） - 在
composer.json中注册为脚本："scripts": { "build": ["php bin/build.php", "npm run build"] } - PHP 脚本内可用
$_SERVER['argv']接收参数，用exec()或proc_open()调用子命令并检查$return_code
如何让脚本感知 Composer 运行上下文
Composer 会注入一组环境变量，比手动传参更可靠：
-
COMPOSER_DEV_MODE：值为1或空，对应--dev/--no-dev -
COMPOSER_COMMAND：当前执行的命令名，如install、update -
COMPOSER_EVENT：事件名，如post-install-cmd、pre-autoload-dump -
COMPOSER_HOME和COMPOSER_VENDOR_DIR：可用于定位路径
示例：在 bin/build.php 中根据环境决定是否压缩 CSS：
<?php
if (getenv('COMPOSER_DEV_MODE') !== '1') {
exec('cssnano public/css/app.css -o public/css/app.min.css', $output, $exitCode);
if ($exitCode !== 0) {
throw new RuntimeException('CSS minification failed');
}
}
避免常见陷阱：路径、权限与并发
本地开发和 CI 环境行为差异往往源于路径假设和权限模型不同：
- 不要硬编码
./vendor/bin/xxx，改用dirname(__DIR__) . '/vendor/bin/xxx'或exec('which xxx') - CI 环境（如 GitHub Actions）默认不加载用户 shell 配置（
~/.bashrc），PATH 可能不含node或php，需显式指定完整路径或先which php - 多个
post-*脚本并发执行时，不要依赖临时文件名（如tmp.log），应加入 PID 或时间戳：tmp_'.getmypid().'.log - 如果脚本修改了
vendor/或autoload.php，记得在最后调用composer dump-autoload，否则后续脚本可能加载不到新类
真正复杂的构建流程（比如生成 API 客户端、校验 schema、推送镜像）从来不是靠 Composer Scripts 驱动的，它只是入口门铃——按下去，后面的事交给专精的工具去做。
