laravel创建项目步骤详解及命令教程

创建 Laravel 项目的核心路径可以概括为三个阶段：首先确认本地已安装合格的 PHP 运行时及 Composer 包管理器；随后通过 composer create-project 或 laravel new 命令行工具拉取应用骨架与核心依赖；最后配置环境密钥与写入权限并启动验证。本文将按照实际开发流程，完整拆解准备工作、创建命令、核心配置及验证步骤，并针对容易混淆的概念和高频报错提供排查依据。

一、创建项目前的环境准备

Laravel 是现代 PHP 生态中的全功能 Web 框架，其底层依赖诸多的语言新特性与核心扩展。在执行创建命令前，必须先在终端中验证基础运行环境是否就绪，避免因版本不兼容或扩展缺失导致安装过程中断。

1. PHP 版本与扩展检查

当前主流的 Laravel 版本（Laravel 10 及 Laravel 11）要求 PHP 版本不低于 8.2。请在终端执行以下命令确认本地 PHP 版本：

php -v

除了版本号，Laravel 还需要一组基础扩展支持数据加密、国际化字符串处理、DOM解析与数据库通信。通过以下命令查看已加载的模块：

php -m

在输出列表中，确保包含 openssl、pdo、mbstring、tokenizer、xml、ctype 与 curl。如果缺失关键扩展，需要在 php.ini 中取消对应模块的注释，或者通过操作系统的包管理器（如 apt install php-mbstring 或 brew install php）补齐。

2. Composer 包管理工具检查

Laravel 的整个框架骨架和第三方库全部通过 Composer 进行调度。执行以下命令核对 Composer 是否正常工作：

composer -V

建议使用 Composer 2.x 版本。如果版本较低，可执行 composer self-update 完成升级，以获得更快的依赖解析速度和更低的内存占用。

二、创建 Laravel 项目的核心命令与操作步骤

官方提供了两种主要的创建命令。二者在最终生成的代码骨架上完全等价，但在使用场景和前置依赖上有所侧重。

方式一：通过 Composer create-project 创建（推荐标准）

这是最直接、最标准的方法，不需要在全局环境中预装任何专用工具。只要系统里有 Composer，即可在目标工作目录下执行：

# 进入你希望存放项目的根目录，例如 workspace/
cd /path/to/workspace

# 执行创建命令，example-app 为项目自定义目录名
composer create-project laravel/laravel example-app

如果业务项目必须锁定在特定的 Laravel 主版本（例如团队统一使用 Laravel 10），可以在命令末尾指定版本约束参数：

composer create-project laravel/laravel:^10.0 example-app-v10

在此过程中，Composer 会自动完成四件事：克隆官方应用模板仓库、下载所有声明的依赖包并生成 composer.lock、将 .env.example 复制为 .env、调用 Artisan 生成唯一的应用加密密钥（APP_KEY）。

方式二：使用全局 Laravel 安装器创建

Laravel 安装器（Laravel Installer）是一个全局 Composer 包。它为本地开发提供了交互式的创建体验，允许在新建项目时直接选择预设套件、数据库类型及测试工具。

首先全局安装安装器：

composer global require laravel/installer

安装完成后，需确保 Composer 的全局 bin 目录已被加入系统的 $PATH 环境变量中（Linux/macOS 通常位于 $HOME/.composer/vendor/bin 或 $HOME/.config/composer/vendor/bin）。确认配置生效后，即可在任意目录运行：

laravel new example-app

新版安装器会以交互式提问引导开发者选择数据库驱动（SQLite、MySQL、PostgreSQL 等）、是否初始化 Git 仓库以及是否安装 Breeze/Jetstream 等认证脚手架。

三、项目生成后的核心配置与权限设置

完成依赖拉取并不等于可以直接交付运行。在正式启动之前，必须进入项目根目录核对环境配置和文件系统权限。

1. 环境变量与应用密钥确认

进入刚刚创建的项目目录：

cd example-app

检查根目录下是否存在 .env 文件。该文件包含了数据库连接、缓存驱动和核心密钥配置。如果不存在（常见于从 Git 仓库拉取模板或非完整安装场景），需手动从模板复制：

cp .env.example .env

打开 .env 文件，观察 APP_KEY 项。如果该项为空，必须通过 Artisan 命令重新生成：

php artisan key:generate

此命令会在 .env 中写入诸如 base64:Xxxxxxxxx... 的 32 位随机字符串。这是 Laravel 用于加密用户 Cookie、Session 及敏感数据的唯一凭证。若该值缺失，应用在处理任何加密会话时都将直接抛出运行时异常。

2. 核心目录的可写权限设置

在 Linux 或 macOS 开发环境中，Laravel 需要对本地磁盘的两个关键路径具有写入权限：

• storage/ 目录：存放系统日志（logs/laravel.log）、已编译的 Blade 模板缓存、文件上传暂存区及文件型 Session。
• bootstrap/cache/ 目录：用于存放框架优化后的路由、服务提供者和配置缓存文件。

如果是在本地开发环境，可以为当前用户和 Web 服务组设置读写权限：

# 赋予所属组写入权限
chmod -R 775 storage bootstrap/cache

# 若通过 Nginx/Apache 运行，需将所有权赋给对应的 Web 用户（如 www-data）
# sudo chown -R www-data:www-data storage bootstrap/cache

四、启动本地服务与安装结果验证

为了在不配置复杂 Nginx/Apache 虚拟主机的前提下快速验证项目，Laravel 自带了基于 PHP 内置 Web 服务器的 Artisan 启动命令。

在项目根目录下执行：

php artisan serve

若默认的 8000 端口已被占用，或者需要在局域网内其他设备上测试，可通过参数调整监听端口与绑定地址：

php artisan serve --host=0.0.0.0 --port=8080

五、新手常见误区与典型报错排查

在初次创建项目时，开发者常因环境差异或概念理解偏差遇到中断。以下梳理典型问题及明确的处理方案。

1. 认知纠偏：是否必须全局安装 Laravel 安装器？

很多初学者误以为创建项目的第一步“必须”是在系统中全局安装 laravel/installer。这种理解看似合理，因为部分教程将 laravel new 作为唯一入口。但在实际工程中，这个说法并不完全成立：

• 合理之处：安装器确实提供了最简洁的命令别名，并在 Laravel 11 中提供了丰富的终端交互向导，适合高频创建试验项目的本地开发机。
• 需要修正之处：安装器本质上只是对 Composer 底层命令的封装。在持续集成管道（CI）、Docker 镜像构建或受限的服务器环境中，额外引入全局安装器不仅增加了维护负担，还可能因为全局依赖版本陈旧引发冲突。直接使用 composer create-project laravel/laravel 是更加通用、纯粹且稳定的工业标准。

2. 典型问题一：缺少必要 PHP 扩展终止安装

报错表现：在执行 Composer 命令时，终端输出类似以下信息：

原因与修复：Composer 在安装前会校验当前 PHP 环境的扩展清单。缺失时必须在系统层补齐，例如在 Ubuntu/Debian 上执行 sudo apt install php-mbstring php-xml php-curl；若在 macOS 使用 Homebrew，通常需检查 php -m 确认对应拓展配置是否在 php.ini 中被激活。

3. 典型问题二：storage 目录写入权限不足（Permission denied）

报错表现：启动后访问页面，浏览器显示 500 内部服务器错误，或终端报错：

原因与修复：当前运行 PHP 服务的进程用户对 storage/ 目录树没有写入权限。执行以下命令重新递归赋权即可解决：

chmod -R 775 storage bootstrap/cache

4. 典型问题三：页面提示 No application encryption key specified

报错表现：访问站点时提示 RuntimeException: No application encryption key has been specified.。

原因与修复：这是由于 .env 文件中的 APP_KEY 为空。通常发生在通过 Git 克隆已有项目或直接解压源码包时。只需在项目根目录运行 php artisan key:generate，随后刷新页面即可恢复正常。

5. 典型问题四：Composer 下载缓慢或网络超时

报错表现：依赖下载停滞在某一组件，最终报错 Operation timed out。

原因与修复：默认的 Packagist 官方服务器位于海外，受网络波动影响较大。国内网络环境下建议切换为镜像源：

# 配置为国内镜像源
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

# 若报内存溢出错误，可在执行命令前临时解除内存上限
COMPOSER_MEMORY_LIMIT=-1 composer create-project laravel/laravel example-app

六、创建步骤标准流程清单总结

为了在日常开发中形成快速、准确的操作直觉，可以将全流程凝练为以下标准操作指令清单：

# 1. 验证运行环境
php -v && composer -V

# 2. 拉取骨架项目（以 my-app 为例）
composer create-project laravel/laravel my-app

# 3. 进入项目目录
cd my-app

# 4. 核验环境文件与生成密钥（如果命令执行期未自动触发）
test -f .env || cp .env.example .env
php artisan key:generate

# 5. 配置可写权限（Linux/macOS）
chmod -R 775 storage bootstrap/cache

# 6. 启动本地服务进行验证
php artisan serve

完成上述各步骤后，即可基于标准的 Laravel 工程骨架开展路由编写、模型迁移与业务逻辑实现。