Composer scripts 是事件与命令的映射表，必须定义在 composer.json 顶层 scripts 字段，键名拼写、缩进、类型均需严格正确；调用需用 composer run 或 run-script；钩子触发时机受限，推荐显式执行；PHP 类需手动加载 autoload；脚本在项目根目录运行，路径应锚定。
Composer 的 scripts 不是“写个 shell 脚本就能跑”的自动化工具，它本质是一张事件与命令的映射表——配错位置、拼错键名、或误以为它会自动加载类，任务就静默失败。
脚本必须定义在 composer.json 顶层 scripts 字段里
这是最常踩的坑：把 scripts 嵌在 extra、config 或缩进错一层，Composer 就直接忽略，不报错也不执行。
-
scripts是和require、autoload同级的顶层字段，不是子配置 - 键名不能是
script（少个 s），必须是scripts；拼成scrpts也一样失效 - 值必须是对象（即 JSON 中的
{}），不能是字符串或数组；空对象{}合法，但没用 - 自定义脚本名建议用小写字母+短横线，比如
build-assets，避免空格、下划线或大写
调用方式必须用 composer run 或 composer run-script
很多人写完 "sync-config": "cp .env.example .env"，然后敲 composer sync-config，结果提示 Command "sync-config" is not defined——因为 Composer 没注册这个子命令。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 新版本（2.2+）统一用
composer run sync-config - 老版本只能用
composer run-script sync-config - 内置事件如
post-install-cmd会自动触发，但你仍可手动运行composer run post-install-cmd测试 - CI 环境务必加
--no-interaction，否则像php artisan migrate这类命令可能卡在确认提示上
post-install-cmd 和 post-update-cmd 并不总按你想的时机执行
这两个钩子看似万能，但实际触发逻辑很具体：它们只在 composer install 或 composer update **成功完成且锁文件有变更**时才走。如果 lock 没变，install 可能直接跳过，钩子就不跑了。
- 真正稳定触发的只有
post-autoload-dump（每次 autoloader 重建必走，包括 install/update/dump-autoload） -
post-root-package-install仅在项目首次安装（如create-project）时触发一次，不适合日常部署 - 想确保每次部署都清缓存？别只靠
post-install-cmd，CI 流水线里显式加一行composer run clear-cache更可靠 - 生产环境部署建议加
--no-scripts显式禁用所有钩子，避免开发用脚本意外执行
PHP 类无法直接调用，autoload 必须手动加载
脚本进程是独立启动的，不会自动 require vendor/autoload.php。写 "MyAppDeploy::run" 会直接报 Class 'MyAppDeploy' not found，哪怕类已声明在 autoload 里。
- 推荐做法：写一个独立 PHP 文件，比如
scripts/deploy.php，开头就require __DIR__.'/../vendor/autoload.php'; - 然后在
scripts里写"deploy": "php scripts/deploy.php" - 若坚持用内联 PHP，得写成
"php -r "require 'vendor/autoload.php'; (new MyApp\Deploy)->run();""，但难维护、易出错 - 调用
vendor/bin/下的命令（如php-cs-fixer）没问题，但别依赖全局安装——路径必须明确，例如php vendor/bin/php-cs-fixer fix
最易被忽略的一点：所有脚本都在项目根目录执行，但当前 shell 的 $PWD 不一定等于项目根目录；如果你在子目录里运行 composer run，而脚本里又用了相对路径（如 cp config/app.php ./storage/），就会操作错地方。统一用 ${PWD}/storage 或 $(pwd)/storage 锚定路径，比靠 cwd 更稳。
