Laravel安装教程：PHP环境配置与Composer创建第一个项目

云舒

发布时间：2026-09-20 | 5人浏览过

原创

在本地搭建 Laravel 开发环境的核心流程分为三步：准备满足版本与扩展要求的 PHP 解释器、安装并配置 PHP 依赖管理工具 Composer，最后通过 Composer 命令行拉取 Laravel 官方框架脚手架并完成基础运行测试。本文将按实际操作顺序拆解各环节的技术要求、具体配置参数与常见问题排查。

场景说明：假设你刚在一台全新的开发机上完成系统安装，终端中尚未配置任何 PHP 工具链。如果在未安装依赖管理器的情况下直接去下载框架源码，会因缺少核心扩展和第三方库而无法启动。按照“PHP 基础环境 → Composer 工具链 → 初始化项目工程”的路径推进，能从源头上避开依赖缺失与扩展未启用的错误。

一、整体装配流程概览

开始动手配置之前，先理清 Laravel 核心基础设施与系统各组件之间的衔接关系。Laravel 是一个由多个模块组合而成的现代化 PHP 框架，它高度依赖底层的 CLI 运行时扩展与 Composer 包版本锁定机制。

图 1：Laravel 环境配置与工程初始化的前后置依赖关系

二、PHP 基础环境与扩展配置

当前主流维护的 Laravel 框架版本（如 Laravel 11 及后续更新）普遍要求 PHP >= 8.2。在安装框架前，必须确保系统已具备对应版本的 PHP CLI（命令行界面）程序，并且启用了框架运行所需的全部底层扩展。

1. 验证 PHP 版本及路径

打开终端（Windows 环境推荐使用 PowerShell 或 Windows Terminal，macOS/Linux 使用原生 Terminal），执行以下命令检查 PHP 现状：

php -v

预期终端输出示例：

PHP 8.2.18 (cli) (built: Apr 11 2024 10:22:45) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.2.18, Copyright (c) Zend Technologies

如果系统提示 command not found 或 不是内部或外部命令，说明 PHP 未加入系统环境变量 PATH 中。需要将包含 php.exe（Windows）或二进制文件的路径添加至环境变量后，重启终端再次检测。

2. 核心扩展检测与 php.ini 修改

Laravel 在启动时会依赖数据加密、字符集编解码、哈希校验等功能。执行以下命令，列出当前已启用的扩展列表：

php -m

请核查输出列表中是否包含以下核心扩展。若缺失任意一项，后续执行 Composer 安装时就会发生依赖中断：

扩展名称	Laravel 中的核心作用	未开启时的典型报错表现
`openssl`	负责 HTTPS 请求与应用安全密钥（APP_KEY）加解密	Composer 无法拉取包，加密模块抛异常
`pdo` & `pdo_mysql`	数据库统一抽象接口与 MySQL 驱动连接	Database driver [mysql] not supported
`mbstring`	多字节字符处理，支持国际化文本计算	Call to undefined function mb_detect_encoding
`tokenizer`	PHP 源代码分词处理，框架路由与配置解析必须	Artisan 无法解析服务容器中的配置类
`xml` / `ctype`	XML 树生成、基础字符类型断言	Composer 依赖解析中断，基础工具无法运行
`curl`	网络资源请求，供 HTTP Client 模块使用	外部 API 请求失败，Composer 无法下载分发文件

若需要启用扩展，首先通过命令找到当前正在使用的配置文件路径：

php --ini

在输出的 Loaded Configuration File 一行确认具体文件（例如 /etc/php/8.2/cli/php.ini 或 C:\php\php.ini），用文本编辑器打开该文件，搜索对应扩展名，去除前面的分号 ; 注释：

; 找到以下行并移除行首的分号
extension=curl
extension=fileinfo
extension=mbstring
extension=openssl
extension=pdo_mysql

保存文件后，再次运行 php -m，确保上述扩展均出现在列表中。

三、Composer 的安装与源配置

Composer 是 PHP 生态的核心依赖管理工具。它并不是用来“运行”Laravel 的，而是负责根据 composer.json 和 composer.lock 中的定义，将框架核心代码及数百个第三方组件下载并组装到项目的 vendor 目录下。

1. 检查 Composer 状态

执行以下命令验证系统中是否已有全局 Composer：

composer --version

预期终端输出示例：

Composer version 2.7.2 2024-03-11 17:12:18
PHP version 8.2.18 (cli)

确保主版本为 Composer 2.x。如果依然是 Composer 1.x，解析依赖的速度会极慢，甚至无法识别部分新版本语法规范，应执行 composer self-update 升级。

2. 配置国内镜像源（可选但推荐）

Composer 官方默认的 Packagist 服务器位于海外。在国内网络环境下直接拉取仓库，容易出现下载缓慢或网络握手超时（cURL error 28）。建议在全局配置阿里云或华为云镜像源以加快拉取速度：

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

配置完成后，可通过以下命令确认当前全局配置生效情况：

composer config -g --list | grep repositories.packagist.org.url

（Windows PowerShell 用户可执行：composer config -g --list | Select-String "packagist"）

四、使用 Composer 创建第一个 Laravel 项目

创建 Laravel 工程有两种常见方式：使用全局 Laravel 安装器，或直接调用 Composer 内置的 create-project 命令。对于初次接触的开发者，直接使用 create-project 是最透明且不容易出错的方法，它无需在系统里额外维护一个安装器命令行工具。

图 2：Composer 创建 Laravel 项目时的内部操作步骤

1. 执行项目初始化命令

在终端中切换到你打算存放代码的目录（例如 /Users/name/Projects 或 D:\Projects），执行下列命令，其中 my-first-app 为你的工程目录名：

composer create-project laravel/laravel my-first-app

终端下载过程的关键输出节选：

Creating a "laravel/laravel" project at "./my-first-app"
Installing laravel/laravel (v11.0.0)
  - Downloading laravel/laravel (v11.0.0)
  - Installing laravel/laravel (v11.0.0): Extracting archive
Created project in /path/to/my-first-app
Loading composer repositories with package information
Updating dependencies
Locking 105 packages to .lock releases
...
Generating optimized autoload files
> @php -r "file_exists('.env') || copy('.env.example', '.env');"
> @php artisan key:generate --ansi
Application key set successfully.

命令执行结束后，当前目录下会出现一个名为 my-first-app 的独立文件夹。

2. 进入项目并确认核心配置文件

切换进入刚创建的目录：

cd my-first-app

使用命令查看文件列表（Linux/macOS 执行 ls -la，Windows 执行 dir /a）。请重点观察以下文件是否存在：

.env：项目运行的环境变量配置文件（包含了数据库凭证、APP_ENV、APP_KEY 等）。如果缺少此文件，Laravel 将无法启动。
vendor/：所有由 Composer 管理下载的代码依赖库都存放于此。在 Git 等版本管理中，该目录默认被忽略。
artisan：Laravel 的命令行工具入口文件，用于执行数据库迁移、生成代码模板和启动开发服务器。

安全提醒：在生产部署或多人协作时，绝不能将 .env 提交到公共代码仓库中。每个新环境均通过 cp .env.example .env 产生新配置，再手动运行 php artisan key:generate 来重新生成专属的应用密钥。

五、启动内置开发服务器并验证结果

Laravel 内置集成了对 PHP CLI Server 的调用封装，通过命令行工具 artisan 即可在几秒内启动本地调试服务，无需立即安装大型的 Nginx 或 Apache 软件。

1. 启动 Artisan 调试服务

确保终端所在路径处于 my-first-app 根目录，执行：

php artisan serve

服务启动后的输出内容：

   INFO  Server running on [http://127.0.0.1:8000].

  Press Ctrl+C to stop the server

这表明开发服务器已经监听了本机的 8000 端口。保持该终端窗口处于运行状态，不要将其关闭。

2. 浏览器访问验证

打开电脑上的任意主流浏览器，在地址栏中输入：

http://127.0.0.1:8000

如果配置正确，你将看到 Laravel 官方内置的欢迎仪表盘页面。该页面展示了当前安装的框架主版本、底层 PHP 版本以及基础文档入口。这标志着 PHP 运行时、Composer 依赖包以及应用密钥配置已经完整贯通。

端口冲突处理：如果 8000 端口已被其他本地进程占用，系统会自动尝试 8001，或者你可以手动指定监听端口：
php artisan serve --port=8080

六、底层架构与目录组织形态

为了在后续编码中清楚地知道代码应该写在哪里，需要对新生成的项目目录职责形成清晰认识。以下架构图展示了请求进入项目的流转方式及核心目录分布：

图 3：Laravel 核心工作目录的职责分工与安全边界

七、安装过程中的常见报错与修复方案

在创建和初始化项目的过程中，若环境存在隐形缺陷，通常会在终端暴露具体错误信息。以下是出现频次最高的几类问题与具体对应修复手段：

1. 报错提示：No application encryption key has been specified

成因：项目根目录下的 .env 文件不存在，或者 .env 中的 APP_KEY= 处于空白状态。缺少该密钥时，出于安全保护机制，Laravel 会主动拒绝处理所有 HTTP 会话和加密计算。

修复操作：

若无 .env 文件，先通过模板复制：cp .env.example .env
在项目根目录下生成新密钥：php artisan key:generate
重新刷新浏览器页面，错误即解除。

2. 报错提示：The Process class relies on proc_open, which is not available

成因：部分环境（尤其是在 Linux 宝塔面板、LNMP 一键包或共享主机中）为了所谓安全性，在 php.ini 的 disable_functions 中禁用了 proc_open、proc_get_status 等函数。然而，Composer 依赖下载与 Artisan 内部进程调用严重依赖此类函数。

修复操作：打开使用的 php.ini 文件，搜索 disable_functions，从列表中删除 proc_open 与 proc_get_status，保存后重启命令行或 PHP-FPM 服务。