composer安装Laravel 10教程_环境要求检测与一键式项目创建【实操】

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 缓存、文件权限这三处状态看不见摸不着，出问题时错误信息却指向其他地方。