composer如何创建项目的骨架_create-project自定义模版使用【详解】

composer create-project 本质是克隆远程仓库并执行 composer install，不运行脚手架或模板渲染；需目标包 type 为 project，通过 scripts 中 post-root-package-install 触发初始化脚本。

composer create-project 本质是克隆并安装，不是“生成”

它不运行脚手架代码，也不执行模板引擎渲染——只是把远程仓库（如 gitHub）的整个目录 git clone 下来，然后运行 composer install。所谓“自定义模板”，实际是维护一个已预设好结构、依赖和脚本的 Composer 包（通常为 type: project），由你托管在 Git 服务器上。

如何用 create-project 拉取私有/定制骨架

前提是目标仓库的 composer.json 中声明了 "type": "project"，且根目录下有完整可运行的项目结构（如 public/、src/、index.php 等）。执行时指定包名和目标目录即可：

composer create-project vendor/my-skeleton my-app --stability=dev --no-interaction

• vendor/my-skeleton 必须已在 Packagist 注册，或已配置私有仓库源（如 composer config repositories.mygit vcs https://git.example.com/my-skeleton）
• --no-interaction 避免交互式提问（如是否删除已有目录），CI/CD 中必需
• --stability=dev 若骨架仅发布在 dev-main 分支，需显式允许不稳定版本
• 若想跳过 composer install（例如后续手动处理），加 --no-install；但绝大多数情况不建议

create-project 后自动执行脚本的关键：scripts + post-root-package-install

真正实现“初始化逻辑”的地方是 composer.json 的 scripts 段。框架级骨架（如 laravel、symfony）靠这个完成环境文件复制、密钥生成等操作：

{     "scripts": {         "post-root-package-install": [             "@php -r "file_exists('.env') || copy('.env.example', '.env');"",             "@php artisan key:generate"         ]     } }

• post-root-package-install 是唯一在 create-project 流程中触发的事件（注意不是 post-create-project-cmd —— 该事件只在 composer create-project 命令本身被调用时触发，但**仅当当前目录是空的且未安装任何包时才生效**，行为不可靠，官方已不推荐）
• 脚本中调用 php 或 bin/console 等二进制时，路径要写全或确保在 $PATH 中；相对路径以项目根目录为基准
• 避免在脚本里做耗时操作（如下载大文件），否则会卡住命令，用户无感知

常见失败原因和绕过方式

拉取失败往往不是模板问题，而是权限或配置链路断裂：

• 报错 Could not find package vendor/my-skeleton：确认 composer show vendor/my-skeleton 能查到；若为私有 Git，检查 auth.json 是否配置了 Token，且仓库 URL 协议用 https 或 ssh 一致
• 报错 Failed to execute git clone ... fatal: could not read Username：Git 凭据未缓存，改用 https://token:x-oauth-basic@github.com/... 形式写入 repositories，或配置 git config --global credential.helper store
• 脚本执行失败但命令返回 0：Composer 默认忽略脚本退出码；加 "script-action": "die" 到 config 段可让失败中断流程（需 Composer 2.5+）
• 想替换占位符（如 {{APP_NAME}}）？Composer 不提供变量替换功能；必须自己写 PHP 脚本读取并替换文件内容，或改用专用工具如 cookiecutter + composer create-project 组合

真正难的不是拉代码，而是让骨架具备可维护性：版本分支对齐、脚本幂等、错误提示明确。很多人卡在第一次 CI 构建失败，其实只是忘了在 GitHub Actions 里 git config --global url."https://${{ secrets.TOKEN }}@github.com/".insteadOf "https://github.com/"。