create-project 本质是下载指定包骨架、执行其初始化脚本并安装依赖，非创建空项目；必须指定包名，支持版本约束与仓库源，但不支持本地路径或git url；常见问题包括目录非空、缓存损坏、权限不足及php路径错误。
create-project 本质是“下载+安装+初始化”，不是从零新建
它不生成空目录再让你写代码，而是从指定包（比如 laravel/laravel）拉取完整项目骨架，执行其 composer.json 中定义的 post-create-project-cmd 脚本（如清空 Git 记录、生成密钥），最后才把依赖装上。如果你想要空白项目，别用这个命令——直接 mkdir + composer init。
必须指定包名，不能只写 composer create-project
漏掉包名会报错：Not enough arguments (missing: "package"). 常见写法：
-
composer create-project laravel/laravel my-app—— 拉最新稳定版 -
composer create-project symfony/skeleton my-app "6.4.*"—— 指定版本约束 -
composer create-project codeigniter4/appstarter my-app --repository-url=https://packagist.org—— 某些私有包需显式指定源
注意：包名必须存在于 Packagist 或你配置的私有仓库中；本地路径或 Git URL 不被支持（要用 composer install 配合 composer.json）。
常见陷阱：权限、缓存、Git 初始化冲突
实际执行时容易卡在几个地方：
- 目标目录已存在且非空 → 报错
Destination Directory "xxx" is not empty.，加--remove-vcs也无效，得先手动清空 - 全局 Composer 缓存损坏 → 出现
Failed to extract xxx: unable to decompress gzipped phar，试composer clear-cache - 项目自带
.git目录，但当前用户无写权限 → 卡在Initializing project...，检查目录属主和umask - 某些框架（如 Laravel）的 post-install 脚本依赖
php可执行文件路径，若系统有多个 PHP 版本且php命令指向旧版，可能生成错误的.env或密钥
比 create-project 更轻量的替代方案
如果只是想快速跑个 Demo，又不想等完整依赖安装，可以跳过自动执行脚本：
-
composer create-project --no-install --no-scripts laravel/laravel my-app→ 只解压骨架，不装依赖也不跑初始化 -
git clone对应仓库 +composer install→ 完全可控，适合调试或定制化强的场景 - 用
composer create-project --prefer-dist（默认）比--prefer-source快，但后者方便你直接改 vendor 里的代码（不推荐生产用）
真正麻烦的从来不是命令本身，而是它背后隐含的“信任链”：你信这个包的 composer.json、信它的脚本逻辑、信你的本地环境能正确执行它——哪一环松动，都会在看似最简单的一步上卡住。