绝大多数Laravel安装失败的根本原因是本地环境不达标或关键配置被跳过：PHP版本不符（如Laravel 10需≥8.1）、必需扩展（openssl/mbstring/tokenizer/zip）缺失、Composer镜像被墙、.env未复制及APP_KEY未生成、Web服务器重写规则未配或DocumentRoot指向错误。
绝大多数 Laravel 安装失败，根本原因不是框架本身，而是本地环境没达标或关键配置被跳过。直接看下面这几个高频卡点。
PHP 版本或扩展缺失
Laravel 10 要求 PHP ≥ 8.1，Laravel 9 是 ≥ 8.0，5.5 则只要 ≥ 5.6.4 —— 但很多人用默认的 XAMPP/WAMP 或旧版 phpstudy，自带 PHP 还是 7.2 甚至更低。php -v 一眼就能确认。更隐蔽的是扩展：缺 openssl、mbstring、tokenizer 中任意一个，composer create-project 都会中途报错退出，错误信息常含 Call to undefined function 或直接中断无提示。
- 检查命令：
php -m | grep -E "openssl|mbstring|tokenizer"（Linux/macOS）或php -m手动扫一遍（Windows） - Windows 下 phpstudy 用户：必须重装 ≥ 7.1 的版本包，旧版即使勾选了扩展也可能未真正启用
- Linux 编译安装 PHP 的用户：
./configure时漏掉--with-openssl等参数，光装openssl-devel不够
Composer 下载被墙或 zip 扩展未启用
国内直连 https://repo.packagist.org 极大概率超时，表现是卡在 Installing laravel/framework (v10.48.12) 几分钟不动，最后报 Failed to download laravel/laravel from dist。另一个常见静默失败是系统没装 zip 命令或 PHP 的 zip 扩展未开启，错误里会明确写 The zip extension and unzip command are both missing。
- 换镜像：运行
composer config -g repo.packagist composer https://packagist.phpcomposer.com（旧版）或composer config -g repo.packagist https://mirrors.aliyun.com/composer/（新版） - 验证 zip：终端执行
zip --version；再运行php -m | grep zip，没输出就说明 PHP 扩展没开 - Windows 用户注意：
php.ini里要取消注释extension=zip，且确保php-zip.dll文件真实存在
.env 文件缺失或 APP_KEY 未生成
项目目录建好了，php artisan serve 也能跑起来，但一访问就弹 RuntimeException: No application encryption key has been specified —— 这不是安装失败，是初始化没走完。新项目默认只有 .env.example，没人手动复制+生成密钥，Laravel 就拒绝启动。
- 必须执行两步：
cp .env.example .env（Linux/macOS）或copy .env.example .env（Windows），然后php artisan key:generate - 如果报
file_put_contents(.env): failed to open stream，说明当前用户对项目根目录没写权限，别硬改权限，先cd进去再执行 - 某些 IDE（如 PHPStorm）默认隐藏点文件，看不到
.env就以为没生成，其实是被过滤了
Apache/Nginx 重写规则没配或 DocumentRoot 指向错误
用集成环境（XAMPP、WampServer）或自己搭 Web 服务器时，常见现象是首页能打开，但点任何链接都 404，或者直接显示 Whoops, looks like something went wrong. 且没堆栈。这不是 Laravel 没装好，是请求根本没进 Laravel 的入口 public/index.php。
- Apache：确认
httpd.conf启用了mod_rewrite，且项目目录的<directory></directory>块里AllowOverride设为All，不是None - Nginx：root 必须指向
your-project/public，不是项目根目录；还要加try_files $uri $uri/ /index.php?$query_string; - 最省事验证法：直接浏览器访问
http://localhost/public，能进欢迎页说明 Web 服务通，问题纯属路由配置
真正难排查的，往往是多个条件叠加：比如 PHP 版本够了但少一个扩展，又恰好 Composer 镜像失效，导致你反复重试却只看到不同阶段的报错，误以为是新问题。建议每次只改一个变量，用 php -v、php -m、composer diag 逐层确认，比盲目搜错别字高效得多。
