你照着教程敲下 composer create-project 或 laravel new,本以为几秒就能起一个项目,结果终端甩出一串红色报错,卡在半路。先给结论:Laravel 创建工程失败,绝大多数逃不出 PHP 版本与扩展、Composer 版本与网络、目录权限这三类的范围,按这个顺序排查基本都能解决。不同报错只是这三类的不同表现,别急着重装系统。本文把三个坑逐一拆开,每条都给出可复现的命令、典型输出和对应修法,并附一份动手核对清单,帮你从"看不懂报错"变成"照着清单就能定位"。

先看结论
- Laravel 创建工程的报错,主要集中在 PHP 版本/扩展、Composer 版本/网络、目录权限三类。
- 新版 Laravel 对 PHP 版本有下限要求,PHP 版本不够或缺扩展,会在依赖解析阶段直接失败。
- Composer 版本过旧或镜像源不通,是"下载不动、超时、找不到包"的主因。
- 目标目录不可写或已存在非空内容,会导致安装中断,先看权限再看目录状态。
一、坑一:PHP 版本或扩展不满足要求
最常见的第一道坎是 PHP 环境。Laravel 每个大版本都对 PHP 有最低版本要求,较新的 Laravel 版本需要 PHP 8.1 及以上,还要求启用 openssl、pdo、mbstring、tokenizer、xml、ctype、json 等扩展。版本不够或少了扩展,Composer 在解析依赖时就会报错退出。
先看当前环境:
# 查看 PHP 版本
php -v
# 查看已启用的扩展
php -m
上面两条分别打印 PHP 版本号和扩展列表。对照 Laravel 官方文档的版本要求,确认 PHP 版本达标、php -m 里能找到需要的扩展。很多人卡在这一步,是因为本机装了多个 PHP 版本,命令行调用的并不是项目需要的那个。基础语法和扩展说明可以配合 PHP 速查手册 一起核对。
⚠️ 注意:缺扩展时不要去改系统全局配置碰运气。先确认你用的是哪个 php.ini(
php --ini会打印路径),在正确的配置文件里启用扩展,再重启 Web 服务或命令行环境。
二、坑二:Composer 版本过旧或网络不通
确认 PHP 没问题后,第二高频的坑是 Composer。老版本 Composer 可能无法解析新 Laravel 的依赖约束,表现为"找不到符合条件的包"。先升级到最新版:
# 查看当前版本
composer --version
# 升级 Composer 自身
composer self-update
# 升级后再次确认
composer --version
若升级命令报网络错误,多半是默认源访问不通。可以配置国内镜像源再重试。配置后建议清空缓存:
# 清空 Composer 缓存
composer clear-cache
网络问题还有一个典型症状:下载到一半卡住或超时。这类情况先测网络连通性,再考虑换源,不要反复中断重来导致缓存里留下残缺文件。Composer 与 Laravel 的配合逻辑,在 Laravel 8 教程 里有更系统的讲解,遇到依赖概念不清时可以回看。
这里补一个容易被忽略的版本对照视角。不同 Laravel 版本对 PHP 和 Composer 的要求并不相同,升级时若只看教程里的命令、不看版本要求,就会在新旧组合之间反复踩坑。
| Laravel 大版本 | PHP 最低要求 | 说明 |
|---|---|---|
| Laravel 8 | PHP 7.3 起 | 老项目常见,兼容范围较宽 |
| Laravel 10 | PHP 8.1 起 | 当前主流,语法更现代 |
| Laravel 11 及更新 | PHP 8.2 起 | 新项目首选,要求更高 |
这张表说明一个取舍:如果你的运行环境只能装 PHP 7.4,那就选 Laravel 8,不要硬上要求 PHP 8.2 的新版本;反过来,新项目在条件允许时优先用较新版本,能获得更长的安全维护周期。创建工程时其实可以显式指定版本,让 Composer 按你的环境挑:
# 显式创建 Laravel 8 项目,避免 Composer 默认拉最新版导致版本不符
composer create-project laravel/laravel="8.*" my-laravel-app
# 在已有目录里指定版本安装
composer create-project laravel/laravel:^10.0 my-laravel-app
第一条把版本锁在 8.x,适合老 PHP 环境;第二条用 ^10.0 约束到 Laravel 10 系列。显式写版本的好处是结果可预期,不会因为 Composer 默认拉最新版而突然报"PHP 版本不满足"。从性能角度看,版本本身对安装耗时影响不大,主要成本在下载依赖,换一个稳定的镜像源比纠结版本更能省时间。

三、坑三:目录权限或目标目录状态
第三个坑常被忽略:权限和目录状态。composer create-project 要在当前位置新建目录并写入文件,如果父目录不可写,或者同名目录已经存在且非空,安装就会中断。
先看权限和目标目录:
# 查看当前目录权限(Linux/macOS)
ls -ld .
# 查看目标目录是否已存在
ls -ld my-laravel-app
如果发现目标目录已存在且非空,两个选择:换个新名字,或者确认里面没有要保留的内容后清理再装。权限不足时,临时用 sudo 不建议,更稳妥的做法是把项目建在自己有写权限的目录下。
三种坑的现象与修法对应关系如下:
| 现象 | 大概率原因 | 优先动作 |
|---|---|---|
| 依赖解析失败、要求某版本 | PHP 版本或扩展不足 | 查 php -v 与 php -m |
| 找不到包、下载超时 | Composer 旧或网络不通 | 升级 Composer、换镜像源 |
| 写入失败、目录已存在 | 权限不足或目录非空 | 查权限、换目录名 |
动手核对清单
安装与前置
运行 php -v 确认版本达标;运行 php -m 确认必需扩展齐全;运行 composer --version 确认版本较新。
操作
执行 composer create-project laravel/laravel my-laravel-app,观察终端输出。
检查与验证
出现 SUCCESS 或 "Application key set successfully" 表示创建成功;进入目录运行 php artisan --version 能打印版本号即环境正常。
失败处理
版本报错回到坑一;下载报错回到坑二;写入报错回到坑三。每改一处重试一次,不要同时改多项。

总结
Laravel 创建工程出错,看似报错五花八门,实则集中在 PHP 版本与扩展、Composer 版本与网络、目录权限这三处。排查时按"先 PHP、再 Composer、最后目录"的顺序逐项确认,每改一处重试一次,就能稳定定位问题。环境装好只是第一步,真正用好 Laravel 还要理解它的路由、控制器和 ORM,把基础打牢,后面遇到报错才不会每次都从头猜。
常见问题
Q:创建工程时报"requires php ^8.1"之类的错误怎么办?
A:这表示你的 PHP 版本低于项目要求。用 php -v 确认当前版本,升级到要求版本或切换到已安装的高版本 PHP。若本机有多个 PHP,注意命令行调用的是哪一个。
Q:Composer 下载一直超时怎么处理?
A:先测网络连通性,再配置可用的镜像源,然后 composer clear-cache 清掉残缺缓存后重试。避免反复中断下载,否则缓存里会留下不完整文件。
Q:提示目录已存在或权限不足怎么解决?
A:换个新的目录名,或确认旧目录无需要保留的内容后清理。权限不足时,把项目建在你有写权限的路径下,不推荐直接 sudo 安装。

TRAE-AI编程



