Composer 的 scripts 是事件钩子执行器，非 shell 脚本入口，仅支持 PHP 可调用目标（类方法、闭包、PATH 中命令或 vendor/bin/ 二进制），因不自动加载框架 autoloader 且不保证环境一致，故不能直接写 php artisan migrate 等命令。
Composer 的 scripts 是什么，为什么不能直接写 shell 命令
scripts 不是 shell 脚本入口，而是 Composer 内置的事件钩子执行器。它只认 PHP 可调用目标：类方法、闭包、可执行命令（需在 $PATH 中）、或带 vendor/bin/ 前缀的二进制。直接写 php artisan migrate 会失败，因为 Composer 不自动加载 Laravel 的 autoloader，也不保证 artisan 在当前环境可执行。
常见错误现象：Script php artisan migrate handling the post-update-cmd event returned with error code 127 或 Class 'AppConsoleKernel' not found。
- 必须确保脚本目标在 Composer 自动加载范围内，或显式 require
autoload.php - Laravel、Symfony 等框架自带的 CLI 工具（如
artisan、console）应通过vendor/bin/调用，而非全局或项目根目录直写 - PHP 版本和扩展依赖需与脚本实际运行环境一致（例如
ext-pdo_sqlite缺失会导致migrate失败）
在 composer.json 中定义框架脚本的正确写法
以 Laravel 为例，scripts 应聚焦于“可复现、可组合、不依赖当前工作目录”的行为。关键不是“怎么写命令”，而是“谁来执行、在哪执行、用什么上下文执行”。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 使用
vendor/bin/artisan替代php artisan：避免因 PHP CLI 配置差异导致opcache.enable_cli=1等问题 - 加
--no-interaction和--ansi参数提升 CI 兼容性，比如："post-install-cmd": ["@php vendor/bin/artisan migrate --no-interaction --force"] - 若需前置条件检查（如数据库连接），不要塞进 script 字符串里，改用自定义 PHP 类方法，例如：
"pre-deploy": "App\Scripts\PreDeploy::run"，并在autoload["psr-4"]中注册该命名空间 - Symfony 用户注意：
console默认不带--env=prod，生产部署时漏写会导致缓存未预热或配置未编译
如何让脚本在不同环境安全运行（开发 / CI / 生产）
Composer 脚本没有原生环境变量隔离机制，APP_ENV 或 DB_CONNECTION 等全靠外部注入。硬编码在 scripts 里等于埋雷。
- 用
composer run-script <name> -- --env=production传参，脚本内部通过$argv或$_SERVER['argv']获取（仅适用于自定义 PHP 方法） - CI 场景下禁用交互式命令：把
"post-update-cmd"拆成"ci:install"和"ci:test"，并统一在 GitHub Actions 或 GitLab CI 中控制执行顺序 - 敏感操作（如
migrate:fresh）绝不放在post-install-cmd，应单独命名（如"dev:reset-db"），并加注释说明风险 - 避免在脚本中调用
php -r "echo time();"这类临时逻辑——它无法被测试、无法被调试、无法被版本追踪
调试 Composer 脚本失败的三步定位法
报错信息往往藏在表层之下。Composer 输出的 Script ... returned with error code X 只是结果，不是原因。
- 加
-v参数重跑：composer install -v，看完整命令和 stderr 输出；特别注意是否出现PHP Fatal error: Uncaught Error: Class '...' not found - 手动模拟执行：复制脚本字段里的命令，在终端中粘贴运行（注意切换到项目根目录，并确认当前 PHP 版本与
composer --version显示一致） - 检查 autoload 是否生效：运行
composer dump-autoload -o后再试；若用自定义类方法，确认其文件已由autoload["psr-4"]或autoload["files"]加载
最常被忽略的是：脚本定义在 composer.json 里，但修改后没重新运行 composer install 或 composer update —— Composer 不监听 JSON 文件变更，它只读取 vendor/composer/autoload_static.php 生成的结果。
