如何用Composer Scripts简化重复劳动，打造个性化工作流？

本文共计1001个文字，预计阅读时间需要5分钟。

Composer scripts 不是魔法，但能帮你将重复命令变成一键执行的操作——前提是别把它当作 shell 脚本来写，也别指望它自动处理路径或环境差异。

如何在 composer.json 里定义可复用的脚本

Composer 的 scripts 是键值对映射，左边是自定义命令名（比如 dev:setup），右边是实际要执行的命令字符串。它支持 PHP 函数调用、shell 命令、甚至其他 Composer 脚本，但执行上下文受限：当前工作目录是项目根目录，PATH 依赖系统环境，不自动加载 vendor/bin ——所以调用 phpunit 或 php-cs-fixer 时得写全路径或加 vendor/bin/ 前缀。

• 推荐用 vendor/bin/xxx 显式调用工具，避免本地全局安装版本干扰
• PHP 调用必须以 php: 开头，例如 "php:MyScript::run"，且类必须已通过 autoload 加载
• 多个命令用 && 连接，但注意失败时默认不会中断（除非加 set -e 或用 || exit 1）
• 别在脚本里写交互式命令（如 read），Composer 不提供 TTY

composer run 和直接 composer xxx 的区别

从 Composer 2.2 开始，composer run <script-name> 是显式调用方式，而 composer <script-name> 是快捷语法——两者行为一致，但后者会和原生命令（如 composer install）冲突。如果定义了 "test" 脚本，运行 composer test 就会覆盖内置 composer test（其实并不存在，但会遮蔽未来可能的官方命令）。

• 优先用 composer run dev:setup，语义清晰且无冲突风险
• composer run --list 可查看所有可用脚本，含描述（需在 scripts-descriptions 中配置）
• 加 --no-ansi 或 --quiet 可抑制输出，适合 CI 环境

常见错误：脚本执行失败却没报错

最常遇到的是脚本里某条命令出错但整体退出码为 0，导致 CI 流水线误判成功。典型场景包括：

• phpstan analyse src/ || true —— || true 强制返回 0，掩盖问题
• Windows 上用 && 连接命令，但 cmd.exe 不支持该语法（应改用 ^&^& 或切到 PowerShell）
• PHP 脚本中抛异常但没设置 exit(1)，Composer 默认只看返回值，不捕获异常
• 路径含空格或特殊字符，未用引号包裹（如 php vendor/bin/phpunit "tests/Feature/"）

什么时候该用脚本，什么时候该写独立 CLI 工具

Composer scripts 适合轻量、项目级、与依赖强绑定的操作，比如清缓存 + 迁移 + 重载配置；但它不适合复杂逻辑、参数校验、多步骤交互或跨项目复用。

• 需要传参？用 composer run build -- --env=prod，参数透传给脚本，但接收端得自己解析（$argv 或 $_SERVER['argv']）
• 要支持 --help 或子命令？别硬撑，直接写个 bin/mytool，用 Symfony Console 或 Laravel Zero 更稳
• 想让团队成员都用同一套构建逻辑？脚本写在 composer.json 里比文档靠谱，但记得加注释说明用途和前置条件

真正难的不是写脚本，而是判断哪一步该交给 Composer，哪一步该交给 Makefile、GitHub Actions 或专用 CLI 工具——边界模糊时，先跑通再拆分。