如何利用Composer管理内部的脚手架工具？团队开发规范

先聊个基础的，但也是最容易踩坑的点。

新建项目，别一上来就敲 composer init。听我一句劝，直接用 create-project。原因很简单：init 只给你生成一个空荡荡的 composer.json，十行 JSON 代码，啥骨架都没有。你的最终资产应当是一个可被即时实例化的骨架。这个骨架自带公共目录结构、artisan 入口、环境示例文件，以及能自动运行的初始化脚本——而这些恰好是 init 绝对给不了你的。

create-project 做的事要完整得多：它会拉取整个模板包（比如 myteam/skeleton），解压目录，安装依赖，最后触发 post-create-project-cmd 脚本来完成密钥生成、环境文件复制等关键操作。

这里有个细节：内部模板包的 type 必须显式设为 "project"。否则 create-project 根本不认它为一个可实例化的骨架。

脚手架必须用 create-project，别碰 init

• create-project 会拉取整个模板包（比如 myteam/skeleton），解压目录、安装依赖、运行 post-create-project-cmd 脚本（生成密钥、复制环境文件等）
• init 只输出 10 行 JSON，之后还得手动配 autoload、require 框架、建 Git 仓库、设 Web 根目录——多数人卡在第二步
• 内部模板包的 type 必须设为 "project"，否则 create-project 不认它为可实例化骨架

post-create-project-cmd 脚本的放置有讲究

这个钩子只在新项目生成后、首次进入其目录时触发。它只认顶层 scripts 下的 post-create-project-cmd 字段（全小写，不能驼峰，不能漏短横线）。

• 脚本的工作目录是新建项目根目录（如 myapp/），不是模板源码目录，所以路径别写 ../template/src
• 避免交互式操作（如 readline()），CI 环境下会卡住；改用预设值或环境变量注入
• 常见任务：复制 .env.example → .env、运行 php artisan key:generate、清空 .git 并重新 init（避免继承模板仓库历史）

私有模板包的仓库配置不能省略

团队内部脚手架通常托管在私有 Git 仓库（如 GitLab 或 GitHub Enterprise）。不声明 repositories，create-project 就找不到包。

• repositories 必须写在使用方的 composer.json（不是模板包自己的），且 type 设为 "vcs"，URL 用 HTTPS 或 SSH 地址
• 若模板只有 dev-main 分支，需显式加 --stability=dev 参数，否则默认只搜 stable
• 国内访问慢时，临时切回官方源：composer config -g repo.packagist composer https://packagist.org。别长期依赖镜像——私有包往往不在镜像中同步

脚手架模板本身就是团队基建契约

模板包的 composer.json 不是“示例”，而是团队开发环境的起点契约。它必须自带不可绕过的约束。

• "minimum-stability": "stable" + "prefer-stable": true，防止新项目一上来就引入 @dev 包
• "autoload" 严格按 PSR-4 声明，如 "MyTeamApp": "app/"，禁用 files 或 classmap
• "config" 中预置 "sort-packages": true 和 "allow-plugins" 白名单（如 "phpstan/extension-installer"），防插件失控
• "php" 版本约束写在 require 下（如 "php": "^8.2"），不用 platform —— 后者在 CI 中易被忽略

复杂点不在命令怎么敲，而在于模板包是否真把 composer.json 当契约来维护。每次 create-project 都是在签一次约，合约内容错了，后面所有环境一致性都无从谈起。