post-root-package-install事件仅在composer create-project执行完成后触发，此时目标目录已创建、项目代码解压、根composer.json就位但依赖尚未安装，且仅对被创建项目自身的composer.json中定义的脚本生效。
root-package-install 事件到底在什么时候触发
它只在 composer create-project 执行完成、目标包已解压并写入 vendor/ 后触发，且仅限于被创建的项目根目录（即新项目的 composer.json 所在位置）。不是每次 composer install 都会触发，也不是子依赖安装时触发——这点常被误用。
常见错误现象：scripts 中写了 root-package-install，但本地运行 composer install 却没执行，因为该事件根本不会在常规安装中激活。
- 仅对
create-project生效，且要求目标包自身声明了该事件监听 - 监听脚本必须定义在被创建项目的
composer.json的scripts段里，不是模板仓库的composer.json - 若模板包用了
type: project，Composer 才会识别为可初始化项目，否则事件不生效
如何让模板项目响应 root-package-install
关键不是“注册事件”，而是确保模板的 composer.json 同时满足三个条件：声明类型、暴露脚本、绑定事件。缺一不可。
示例配置片段（放在模板项目的 composer.json 中）：
{
"type": "project",
"scripts": {
"post-root-package-install": [
"php ./init-template.php"
]
}
}
注意函数名是 post-root-package-install，不是 root-package-install——Composer 官方只支持 post- 前缀的钩子，root-package-install 本身不是合法事件名。
-
post-root-package-install是唯一可用的对应钩子，文档里常被简写误导 - 脚本文件（如
init-template.php）需放在模板根目录，且有可执行权限或通过php显式调用 - 不要在脚本里依赖
vendor/autoload.php——此时 autoloader 尚未生成，会报错
init-template.php 里能安全做什么
此时 composer.json 已写入，vendor/ 目录已建立但尚未执行 autoload-dump，config/ 或 public/ 等目录还是空的——适合做初始化填充，不适合加载框架类。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
典型操作包括：
- 复制默认配置文件：
cp -n templates/.env.example .env - 生成密钥：
php -r "echo bin2hex(random_bytes(32)) . PHP_EOL;" > .env.key - 重命名占位文件：
mv stubs/app.php app/index.php - 执行
git init并添加初始 commit（如果模板不带 .git）
避免操作：php artisan key:generate（Laravel）、symfony console assets:install 等依赖已安装依赖的命令——vendor 还没 dump autoload，这些命令大概率失败。
为什么 init 脚本有时不执行或静默失败
最常见原因是脚本退出码非 0，但 Composer 默认不抛出错误，只记录日志。用户看到 create-project 成功，却没得到预期文件，以为脚本没运行。
调试建议：
- 在
init-template.php开头加file_put_contents('debug.log', print_r($_SERVER, true), FILE_APPEND);确认是否被执行 - 把脚本第一行改成
#!/usr/bin/env php -d display_errors=1 -d error_reporting=-1强制显示错误 - 检查脚本路径是否拼错，
post-root-package-install是在新项目根目录执行，不是模板仓库路径 - Windows 用户注意换行符和路径分隔符，
copy命令在 shell 脚本里不通用，优先用 PHP 的copy()函数
真正麻烦的是跨平台兼容性——比如用 cp 或 rm -rf 的脚本，在 Windows 下直接失效，而很多人只在自己机器上验证过。
