Composer create-project命令怎么用 创建新项目详细参数说明【文档】

create-project 命令本质是“下载+安装+初始化”三合一操作，从指定包拉取最新稳定版代码、执行 post-create-project-cmd 脚本并安装 require 依赖，适用于框架标准起手式而非新建空目录。

create-project 命令本质是“下载 + 安装 + 初始化”三合一

它不是新建空目录那么简单，而是从指定包（如 laravel/laravel）拉取最新稳定版代码，执行该包定义的 post-create-project-cmd 脚本（比如生成 .env、清空缓存），并安装其 require 依赖。如果你只想要一个空项目骨架，它不适用；你真正需要的是某个框架/项目的标准起手式。

最常用写法和关键参数含义

基础命令格式：composer create-project vendor/name project-dir version --option

• vendor/name：必须，例如 laravel/laravel、symfony/skeleton；不能写成 gitHub 地址或本地路径
• project-dir：可选，不填则用包名自动推导（如 laravel/laravel → laravel 目录）；若目录已存在且非空，命令直接失败
• version：可选，支持 dev-main、2.4.0、^3.0、stable；不填默认取 stable（即最新稳定 tag）
• --no-install：跳过 composer install，适合后续手动控制依赖安装时机
• --no-scripts：跳过执行 post-create-project-cmd 等脚本，常见于调试模板行为异常时
• --remove-vcs：初始化后删掉 .git 目录，避免新项目误提交上游仓库历史

常见报错和对应解法

遇到错误别急着重试，先看输出里最关键的那行：

• Could not find package vendor/name：检查拼写；确认该包在 Packagist 公开可见；私有包需提前配置 repositories
• Project Directory project-dir is not empty：删掉目标目录，或换名；create-project 不覆盖已有内容
• Failed to execute git clone ...：网络问题或 Git 配置异常；可加 --prefer-dist 强制走 zip 包下载
• Script xxx handling the post-create-project-cmd Event returned with Error code 1：说明模板自带脚本出错（如 php artisan key:generate 缺扩展），加 --no-scripts 绕过再排查

和 composer install / require 的根本区别

create-project 是面向“项目初始化”的一次性动作，它会把目标包当作根项目来处理（即写入 composer.json 的 name 字段，并设为 "type": "project"）；而 composer install 是基于现有 composer.json 拉依赖，composer require 是往已有项目里追加依赖。混用会导致 composer.json 结构混乱，比如把 laravel/laravel 当作普通依赖 require 进去，结果得到一个嵌套结构而非标准 Laravel 项目。

真正容易被忽略的是：一旦用了 create-project，后续升级框架版本（如 Laravel 10 → 11）不能靠 composer update 直接升——因为 laravel/laravel 是项目本身，不是依赖项。得按官方迁移指南手动改 composer.json 并清理/重装。