Laravel框架安装避坑指南

为什么选择 Laravel 框架

Laravel 是目前 PHP 生态中最流行的全栈 Web 框架，凭借优雅的语法、强大的 Eloquent ORM、Blade 模板引擎和丰富的官方扩展包，成为众多独立开发者的首选。无论是快速搭建 API 服务，还是开发中大型后台系统，Laravel 都能显著提升开发效率。本文将从零开始，带你完成 Laravel 框架的安装，并总结常见的踩坑点。

安装前的环境准备

在安装 Laravel 之前，需要确保本地环境满足以下条件：

• PHP 版本：Laravel 11 要求 PHP 8.2 及以上，Laravel 10 要求 PHP 8.1 及以上
• Composer：PHP 的依赖管理工具，Laravel 的安装与依赖都依赖它
• 扩展要求：BCMath、Ctype、Fileinfo、JSON、Mbstring、OpenSSL、PDO、Tokenizer、XML 等
• 数据库：MySQL 5.7+、PostgreSQL、SQLite 或 SQL Server 任选其一

可以用 php -m 查看已安装的扩展，用 php -v 确认 PHP 版本。

安装 Composer

Composer 是安装 Laravel 的前置条件。在 Linux 或 macOS 下执行：

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
composer -V

Windows 用户可以直接下载 Composer-Setup.exe 安装包，安装过程中会自动关联 PHP 路径。安装完成后建议配置国内镜像以加速下载：

composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

创建 Laravel 项目的两种方式

方式一：使用 Laravel Installer

Laravel 官方提供的安装器，适合频繁创建项目的开发者：

composer global require laravel/installer
laravel new blog

注意：需要把 Composer 的全局 bin 目录加入 PATH，否则会提示 laravel: command not found。

方式二：使用 Composer create-project

不依赖全局安装器，最通用的方式：

composer create-project laravel/laravel blog
cd blog
php artisan serve

执行完成后访问 http://127.0.0.1:8000，看到 Laravel 欢迎页即表示安装成功。

安装后的基础配置

项目创建后，需要完成几项关键配置：

1. 复制 .env.example 为 .env，并执行 php artisan key:generate 生成应用密钥
2. 在 .env 中配置数据库连接：DB_DATABASE、DB_USERNAME、DB_PASSWORD
3. 执行 php artisan migrate 初始化数据表
4. 设置 storage 和 bootstrap/cache 目录的写入权限

cp .env.example .env
php artisan key:generate
php artisan migrate

常见注意事项与踩坑总结

• PHP 版本不匹配：报错 Your requirements could not be resolved 通常是 PHP 版本或扩展缺失，检查 php -v 和 php -m
• Composer 内存不足：出现 Allowed memory size exhausted 时可以设置 COMPOSER_MEMORY_LIMIT=-1
• 权限问题：Linux 下 storage 目录报错，使用 chmod -R 775 storage bootstrap/cache
• 国内下载慢：配置阿里云或腾讯云 Composer 镜像，能大幅提升速度
• 不要用 root 运行 Composer：会带来安全隐患，建议使用普通用户
• 生产环境不要用 artisan serve：应使用 Nginx + PHP-FPM 部署，并开启 OPcache

小结

Laravel 框架的安装本身并不复杂，真正容易出问题的是环境准备和权限配置。只要提前确认 PHP 版本、扩展齐全、Composer 镜像配置正确，基本可以一次成功。安装完成后建议先跑一遍 php artisan about 检查环境状态，再开始业务开发。掌握这套流程后，你就能快速搭建起属于自己的 Laravel 项目了。