laravel 10 安装前须满足 php ≥8.1.17（禁用 8.1.0）、启用 mbstring/openssl/pdo/tokenizer/xml/ctype/json/curl 扩展、composer ≥2.2，并配置阿里云镜像；执行 create-project 命令时加 --prefer-dist 和 --no-interaction，安装后必须运行 key:generate、设置 storage/bootstrap/cache 权限、校准 .env 中 app_url。
Composer 安装 Laravel 10 前，必须确认环境满足最低要求；否则 create-project 会卡在依赖解析或直接报错，比如 laravel/framework v10.0.0 requires php ^8.1 这类提示不是警告，是硬性拦截。
PHP 版本与扩展检测
Laravel 10 强制要求 PHP ≥ 8.1（不含 8.1.0，建议 8.1.17+ 或直接用 8.2），且必须启用以下扩展：mbstring、openssl、pdo、tokenizer、xml、ctype、json、curl。Windows 用户尤其注意 php.ini 中的 extension=openssl 和 extension=mbstring 是否已取消注释。
- 运行
php -v确认版本号，若显示PHP 8.0.x，composer create-project laravel/laravel myapp会失败 - 运行
php -m | grep -E "mbstring|openssl|pdo"（Linux/macOS）或php -m（Windows）检查扩展是否加载 - 若用 XAMPP/MAMP，别只看面板显示的 PHP 版本——终端里执行
which php和php -i | grep "Loaded Configuration File"才是真实路径
Composer 版本与镜像配置
Laravel 10 的包依赖图更复杂，Composer 2.2+ 是底线，低于 2.2 会出现 Package operations: 0 installs, 0 updates, 0 removals 后静默退出；国内用户不配镜像则大概率卡在 Downloading https://packagist.org/packages.json。
- 执行
composer --version，若输出Composer version 2.1.x，先升级：composer self-update - 临时切阿里云镜像（避免全局污染）：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ - 验证镜像生效：运行
composer diagnose，末尾应出现Repo.packagist.org: OK而非Connection timeout
一键创建 Laravel 10 项目（含常见失败应对）
用 create-project 是最稳妥方式，不推荐 laravel new（它依赖全局 laravel/installer，版本滞后风险高）。关键参数只有两个：--prefer-dist（加速下载）和 --no-interaction（跳过交互式配置）。
composer create-project laravel/laravel myapp --version=10.* --prefer-dist --no-interaction
- 若提示
Could not find package laravel/laravel with version 10.*，说明 Composer 缓存了旧索引，先执行composer clear-cache - 若卡在
Installing dependencies超过 5 分钟，大概率是未启用--prefer-dist导致源码模式拉取太慢 - 成功后进入目录，立刻验证：
cd myapp && php artisan --version应输出Laravel Framework 10.x.x
安装后必须做的三件事
新项目跑起来前，有三个点极易被跳过，但直接影响后续开发：
-
php artisan key:generate—— 不执行会导致Invalid configuration file错误，Session 和加密全部失效 -
chmod -R 755 storage/ bootstrap/cache/（Linux/macOS）或确保 Windows 下storage可写 —— 否则日志写入失败，php artisan serve启动后访问首页报 500 - 检查
.env中APP_URL=http://localhost:8000，若用 Docker 或 Nginx，这里必须和实际访问地址一致，否则 Vue 组件里的axios请求跨域
真正麻烦的不是命令敲错，而是 PHP 版本、Composer 缓存、文件权限这三处状态看不见摸不着，出问题时错误信息却指向其他地方。
