版本号必须作为第三个参数传入,不能用@或=附在包名后,否则因shell解析或Composer误识别导致“Could not find package”等错误;正确写法是composer create-project vendor/name target-dir "version",如"9.*"需加引号防展开。

版本号必须作为第三个参数传入,不能用 @ 或 = 附在包名后面,否则会解析失败或拉错版本。
为什么 laravel/laravel=9.* 这种写法经常失效
这种写法看似直观,但 create-project 命令根本不识别包名里的 = 语法——它会被 shell 当作赋值或重定向处理,也可能被 Composer 当作 package name 的一部分去 Packagist 查找,结果就是 Could not find package laravel/laravel=9.*。官方语法只接受三段式结构:composer create-project vendor/name target-dir version。
常见错误现象:
- 终端报错
Invalid argument或直接卡住无输出(尤其在 zsh 或某些 Windows 终端) - 实际创建的却是最新版(比如想装 8.x 却拉了 11.x),因为版本参数被忽略后默认 fallback 到 stable
- PHP Warning 提示
version_compare(): Argument #2 is not a valid version string,说明传入的字符串未被正确识别为版本约束
正确做法:
- 版本号必须用双引号或单引号包裹,如
"9.*"、"^8.75"、"dev-main" - 引号能防止 shell 展开
*或^,也能避免空格/斜杠引发的分词错误 - 不加引号时,
9.*在 bash/zsh 中可能被当前目录下的文件名匹配并替换,导致命令变形
create-project 的版本参数支持哪些格式
它底层调用的是 Composer 的版本解析器,所以所有 composer require 支持的约束写法,基本都可用,但要注意:不是所有约束在项目模板层面都有对应发布版本。
常用且稳妥的格式:
-
"10.42.*":匹配 10.42 分支的最新 patch 版(推荐用于生产环境锁小版本) -
"^9.0":允许 9.x 全系列,但不升级到 10.x(注意:如果模板没发 9.50+,实际装的可能是 9.0.0) -
"dev-develop":拉开发分支,需加--stability=dev,否则被跳过 -
"2.8.0":精确版本,适合复现旧环境或审计
容易踩的坑:
创建 UCloud UK8S Kubernetes 集群。Use when user asks to "创建 UK8S 集群", "create UK8S cluster", "新建 Kubernetes 集群".
-
"9.x"不是合法约束,Composer 会报Invalid version string;必须写成"9.*" -
"~8.0"行为和^8.0不同:前者等价于>=8.0.0 ,后者是>=8.0.0 ,别凭经验混用 - 某些老模板(如 Laravel 5.x)不提供
dev-master,用"dev-master"会 404,得查 Packagist 页面确认可用分支
PHP 版本不匹配时,create-project 会静默降级
这是最隐蔽的问题:命令不会报错,但会自动选一个“当前 PHP 能装”的最低兼容版本。比如你本地是 PHP 8.0,想装 "9.*",结果却生成了 Laravel 10 —— 因为 Laravel 9 要求 PHP >=8.0.2,而你运行的是 8.0.0;或者你用 PHP 7.4 执行 "10.*",最终落地的是 Laravel 8.x。
验证方式很简单:
- 装完立刻进目录执行
php artisan --version(Laravel)或bin/console --version(Symfony) - 检查
composer.json里require下的laravel/framework实际版本号 - 对比 Laravel 官方要求 或 Symfony 要求,确认 PHP 版本是否达标
临时解决办法:
- 用
php8.1 $(which composer)指定高版本 PHP 运行命令 - 改
composer.json的config.platform.php字段再重试(仅影响依赖解析,不改变运行时 PHP) - 最可靠的是先升级系统 PHP,再跑
create-project
目标目录已存在时的典型报错和绕过方式
create-project 默认拒绝覆盖非空目录,报错信息通常是 Project directory my-app is not empty。这不是 bug,是安全机制——它怕你误删正在写的代码。
但开发中常需要反复试错,比如换镜像、切版本、清缓存。这时可:
- 加
--remove-vcs:删掉.git目录,让命令认为目录“干净”(适合已有 git 仓库但想重拉骨架) - 加
--no-install+ 手动rm -rf vendor composer.lock+composer install:控制权交还给你,但注意这会跳过模板自带的 post-root-package-install 脚本(比如 Laravel 的密钥生成) - 最干脆的是先
rm -rf my-app,再重跑命令——别省这一步,create-project的原子性依赖空目录保证
顺带一提:--keep-vcs 是反向操作,保留原始模板的 .git,适合你想基于官方骨架二次 fork 的场景,但多数人不需要。










