安装

11.x

11.x 10.x 9.x 8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

Laravel 11 中文文档 /

本文档最新版为 10.x，旧版本可能放弃维护，推荐阅读最新版！

安装

认识 Laravel
- 为什么选择 Laravel ?
创建一个 Laravel 项目
初始化配置
使用 Herd 进行本地化安装
- macOS 使用 Herd
- Windows 使用 Herd
使用 Sail 进行 Docker 安装
IDE 支持
下一步
- 将 Laravel 用作全栈框架
- 将 Laravel 用作 API 后端

认识 Laravel

Laravel 是一个 Web 应用框架，有着表现力强、语法优雅的特点。Web 框架为创建应用提供了一个结构和起点，你只需要专注于创造，我们来为你处理细节。

Laravel 致力于提供出色的开发体验，同时提供强大的特性，例如完全的依赖注入，富有表现力的数据库抽象层，队列和计划任务，单元和集成测试等等。

无论你是刚刚接触 PHP Web 框架的新人，亦或是有着多年经验的老手， Laravel 都是一个可以与你一同成长的框架。我们将帮助你迈出成为 Web 开发者的第一步，或是将你的经验提高到下一个等级。我们迫不及待的想看看你的作品。

注意
是第一次使用 Laravel 吗？查看 Laravel Bootcamp 可以让你实际操作 Laravel 框架，并能带你构建第一个 Laravel 应用程序。

为什么选择 Laravel?

有非常多的工具和框架可以被用于构建一个 Web 应用。但我们相信 Laravel 是构建现代化、全栈 Web 应用的最佳选择。

一个渐进式框架

我们喜欢称 Laravel 是一个「渐进式」框架。意思是 Laravel 将与你一同成长。如果你是首次进入 Web 开发， Laravel 大量的文档、指南和视频教程将帮助你熟悉使用技巧而不至于不知所措。

如果你是高级开发人员，Laravel 为你提供了强大的工具用于依赖注入、单元测试、队列、广播，等等。 Laravel 为构建专业的 Web 应用程序进行了微调，并准备好处理企业工作负载。

一个可扩展的框架

Laravel 具有难以置信的可扩展性。由于 PHP 的灵活性以及 Laravel 对 Redis 等快速分布式缓存系统的内置支持，使用 Laravel 进行扩展是轻而易举的事。事实上，Laravel 应用程序已经很容易扩展到每月处理数亿个请求。

需要节省开发费用吗？ Laravel Vapor 允许你在 AWS 最新的无服务器技术上以几乎无限的规模运行 Laravel 应用程序。

一个社区化的框架

Laravel 结合了 PHP 生态系统中最好的软件包，提供了最健壮、对开发人员友好的框架。此外，来自世界各地的数千名有才华的开发人员为框架做出贡献。谁知道呢，也许你就是下一个 Laravel 的贡献者。

创建 Laravel 项目

在创建第一个 Laravel 项目之前，请确保本地计算机已安装 PHP 和 Composer。如果你在 macOS 或 Windows 上开发，可以通过 Laravel Herd 在几分钟内安装 PHP、Composer、Node 和 NPM。

安装好 PHP 和 Composer 后，可以通过 Composer 的 create-project 命令创建一个新的 Laravel 项目：

composer create-project laravel/laravel example-app

或者，你也可以通过 Composer 全局安装 Laravel Installer 来创建新的 Laravel 项目：

composer global require laravel/installer

laravel new example-app

创建项目后，使用 Laravel Artisan 的 serve 命令启动 Laravel 的本地开发服务器：

cd example-app

php artisan serve

一旦你启动了 Artisan 开发服务器，你就可以通过 localhost:8000 访问你的应用程序。接下来，你就可以开始进入 Laravel 生态系统的下一步。当然，你可能还想配置数据库。

注意
如果你想在开发 Laravel 应用程序时抢占先机，可以考虑使用我们的 starter kits。Laravel 入门套件为你的新 Laravel 应用程序提供后端和前端认证脚手架。

初始配置

Laravel 框架的所有配置文件都存储在 config 目录中。每个选项都有文档说明，请随时查阅文件，熟悉可用选项。

Laravel 开箱可用，不需要额外配置，你可以自由地开发！然而，你可能希望查看 config/app.php 文件及其文档。它包含几个选项，例如你可能希望根据应用程序更改 timezone 和 locale。

基于环境的配置

由于 Laravel 的许多配置选项值可能会根据应用程序是在本地机器上运行还是在生产 Web 服务器上运行而有所不同，因此许多重要的配置选项值是在应用程序根目录的 .env 文件中定义的。

你的 .env 文件不应该提交到应用程序的源代码控制中，因为使用你的应用程序的每个开发者/服务器可能需要不同的环境配置。此外，如果入侵者访问了你的源代码仓库，这将成为安全风险，因为任何敏感数据都会被公开。

注意
若要了解更多关于 .env 文件和基于环境的配置的信息，请查看完整的配置文档。

数据库和迁移

现在，你已经创建了 Laravel 应用程序，可能想在数据库中存储一些数据。默认情况下，你的应用程序的 .env 配置文件指定 Laravel 将与 SQLite 数据库交互。

在创建项目的过程中，Laravel 为你创建一个 database/database.sqlite 的文件，并且运行必要的迁移及创建应用程序的数据库表。

如果你更想使用其他数据库驱动，例如 MySQL 或者 PostgreSQL，你可以通过更新 .env 配置文件来使用合适的数据库。例如，如果你希望使用 MySQL 数据库，更新 .env 配置文件的 DB_* 变量如下：

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=

如果你选择使用 SQLite 以外的数据库，则需要创建数据库并运行应用程序的 database migrations:

php artisan migrate

注意
如果你在 macOS 或 Windows 上进行开发，并且需要在本地安装 MySQL、PostgreSQL 或 Redis，请考虑使用 Herd Pro.

目录配置

Laravel应该始终从为你的web服务器配置的“web目录”的根目录中提供服务。而不应该试图在“web目录”的子目录之外为Laravel应用程序提供服务。尝试这样做可能会暴露应用程序中存在的敏感文件。

使用 Herd 进行本地安装

Laravel Herd 是一款速度超快的原生 Laravel 和 PHP 开发环境，适用于 macOS 和 Windows。Herd 包含开始使用 Laravel 开发所需的一切，包括 PHP 和 Nginx。

一旦安装 Herd 后，你就可以开始使用 Laravel 进行开发了。Herd 包含用于 php, composer, laravel, expose, node, npm, 和 nvm 的命令行工具。

注意
Herd Pro 为 Herd 增添了额外的强大功能，例如创建和管理本地 MySQL、Postgres 和 Redis 数据库的能力，以及本地邮件查看和日志监控的能力。

macOS 上的 Herd

如果你在 macOS 上进行开发，可以从 Herd website下载 Herd 安装程序。安装程序会自动下载最新版本的 PHP，并将你的 Mac 配置为始终在后台运行 Nginx。

MacOS 版 Herd 使用 dnsmasq 支持「parked」目录。parked 目录中的任何 Laravel 应用程序都将自动由 Herd 提供服务。默认情况下，Herd 在 ~/Herd 处创建一个 parked 目录，你可以使用其目录名称在 .test 域上访问此目录中的任何 Laravel 应用程序。

安装 Herd 后，创建新 Laravel 项目的最快方法是使用与 Herd 捆绑在一起的 Laravel CLI：

cd ~/Herd
laravel new my-app
cd my-app
herd open

当然，你也可以通过 Herd 的 UI 管理你的 parked 目录和其他 PHP 设置，该 UI 可以从系统托盘中的 Herd 菜单打开。
可以通过查看 Herd 文档了解有关 Herd 的更多信息。

Windows 上的使用 Herd

你可以在 Herd 网站下载 Herd 的 Windows 安装程序。安装完成后，你可以启动 Herd 以完成入门流程并首次访问 Herd UI。

左键单击 Herd 的系统托盘图标即可访问 Herd UI。右键单击可打开快捷菜单，其中可访问你日常所需的所有工具。

在安装过程中，Herd 会在你的主目录中的 %USERPROFILE%\Herd 创建一个「parked」目录。 parked 目录中的任何 Laravel 应用程序都将自动由 Herd 提供服务，并且你可以使用其目录名称在 .test 域上访问此目录中的任何 Laravel 应用程序。

安装 Herd 后，创建新 Laravel 项目的最快方法是使用与 Herd 捆绑在一起的 Laravel CLI。首先，打开 Powershell 并运行以下命令：

cd ~\Herd
laravel new my-app
cd my-app
herd open

你可以通过查看 Windows 版 Herd 文档了解有关 Herd 的更多信息。

使用 Sail 安装 Docker

我们希望尽可能轻松地开始使用 Laravel，无论你喜欢哪种操作系统。因此，有多种选择可用于在本地计算机上开发和运行 Laravel 项目。你或许希望稍后再看这些选项，但 Laravel 提供了 Sail，这是一种使用 Docker 运行 Laravel 项目的内置解决方案。

Docker 是一种在小型、轻量级「容器」中运行应用程序和服务的工具，它不会干扰你本地机器上安装的软件或配置。这意味着你不必担心在本地机器上配置或设置复杂的开发工具（如 Web 服务器和数据库）。要开始使用它，你只需安装 Docker Desktop.

Laravel Sail 是一个轻量级命令行界面，用于与 Laravel 的默认 Docker 配置进行交互。Sail 为使用 PHP、MySQL 和 Redis 构建 Laravel 应用程序提供了一个很好的起点，而无需事先具备 Docker 经验。

[! 注意]
如果已经熟练使用 Docker，可以使用 Laravel 附带的 docker-compose.yml 文件自定义有关 Sail 的所有内容。

在 MacOS 上使用

如果你在 Mac 上进行开发并且已安装 Docker Desktop，则可以使用简单的终端命令创建一个新的 Laravel 项目。例如，要在名为「example-app」的目录中创建一个新的 Laravel 应用程序，你可以在终端中运行以下命令：

curl -s "https://laravel.build/example-app" | bash

当然，你可以将此 URL 中的「example-app」更改为你喜欢的任何内容——只需确保应用程序名称仅包含字母数字字符、破折号和下划线即可。Laravel 应用程序的目录将在你执行命令的目录中创建。

当 Sail 的应用程序容器在你的本地机器上构建时，Sail 的安装可能需要几分钟。

创建项目后，你可以导航到应用程序目录并启动 Laravel Sail。Laravel Sail 提供了一个简单的命令行界面，用于与 Laravel 的默认 Docker 配置进行交互：

cd example-app

./vendor/bin/sail up

启动应用程序的 Docker 容器后，你应该运行应用程序的数据库迁移。

./vendor/bin/sail artisan migrate

最后，你可以在 Web 浏览器中访问应用程序：localhost 。

[! 注意]
要继续了解有关 Laravel Sail 的更多信息，请查看其完整文档。

Windows 使用 Sail

在创建 Laravel 应用前，请确保你的 Windows 电脑已经安装了 Docker Desktop。请确保已经安装并启用了适用于 Linux 的 Windows 子系统 2（WSL2），WSL 允许你在 Windows10 上运行 Linux 二进制文件。关于如何安装并启用 WSL2，请参阅微软开发者环境文档

注意
安装并启用 WSL2 后，请确保 Docker Desktop 已经配置为使用 WSL2 后端。

接下来，你已准备好创建你的第一个 Laravel 项目。启动 Windows 终端并为你的 WSL2 Linux 操作系统开始一个新的终端会话。接下来，你可以使用一个简单的终端命令创建一个新的 Laravel 项目。例如，要在名为「example-app」的目录中创建一个新的 Laravel 应用程序，你可以在终端中运行以下命令：

curl -s https://laravel.build/example-app | bash

当然，你可以根据需要更改此 URL 中的「example-app」- 只需确保应用程序名称仅包含字母数字字符、破折号和下划线。Laravel 应用程序的目录将在执行命令的目录中创建。

Sail 安装可能需要几分钟，因为 Sail 的应用程序容器正在你的本地机器上构建。

项目创建后，你可以导航到应用程序目录并启动 Laravel Sail。 Laravel Sail 提供了一个简单的命令行界面来与 Laravel 的默认 Docker 配置进行交互：

cd example-app

./vendor/bin/sail up

应用程序的 Docker 容器启动后，你应该运行应用程序的数据库迁移：

./vendor/bin/sail artisan migrate

最后，你可以在 Web 浏览器中通过：http://localhost 访问应用程序。

[! 注意]
要继续了解更多关于 Laravel Sail 的信息，请查看其完整文档。

在 WSL2 中开发

当然，你需要能够修改在 WSL2 安装中创建的 Laravel 应用程序文件。我们推荐你使用微软的 Visual Studio Code 编辑器并搭配其 Remote Development 扩展，它们可以帮助你解决这个问题。

一旦这些工具成功安装，你可以使用 Windows 终端在应用根目录执行 code . 命令来打开任何 Laravel 项目。

Linux 使用 Sail

如果你在 Linux 上开发并且已经安装了 Docker Compose，你可以使用一个简单的终端命令创建一个新的 Laravel 项目。

首先，如果你使用的是 Docker Desktop for Linux，你应执行以下命令。如果你没有使用 Docker Desktop for Linux，你可以跳过此步骤：

docker context use default

然后，要在名为「example-app」的目录中创建一个新的 Laravel 应用程序，你可以在终端中运行以下命令：

curl -s https://laravel.build/example-app | bash

当然，你可以根据需要更改此 URL 中的「example-app」 - 只需确保应用程序名称仅包含字母数字字符、破折号和下划线。Laravel 应用程序的目录将在执行命令的目录中创建。

Sail 安装可能需要几分钟，因为 Sail 的应用程序容器正在你的本地机器上构建。

项目创建后，你可以导航到应用程序目录并启动 Laravel Sail。 Laravel Sail 提供了一个简单的命令行界面来与 Laravel 的默认 Docker 配置进行交互：

cd example-app

./vendor/bin/sail up

应用程序的 Docker 容器启动后，你应该运行应用程序的数据库迁移：

./vendor/bin/sail artisan migrate

最后，你可以在 Web 浏览器中通过：http://localhost 访问应用程序。

[! 注意]
要继续了解更多关于 Laravel Sail 的信息，请查看其完整文档。

选择 Sail 服务

通过 Sail 创建 Laravel 程序时，可以使用 with 查询字符串变量来选择应用程序的 docker-compose.yml 文件配置哪些服务。可用的服务包括 mysql, pgsql, mariadb, redis, memcached, meilisearch, typesense，minio, selenium 和 mailpit:

curl -s "https://laravel.build/example-app?with=mysql,redis" | bash

如果不指定配置服务，将使用 mysql, redis, meilisearch, mailpit, 和 selenium 作为默认配置。

还可以通过将 devcontainer 参数添加到 URL 来指示 Sail 安装默认的 Devcontainer:

curl -s "https://laravel.build/example-app?with=mysql,redis&devcontainer" | bash

IDE 支持

在开发 Laravel 应用程序过程中，你可以自由使用任何你喜欢的代码编辑器。不过，PhpStorm 为 Laravel 及其生态系统提供广泛的支持，包括 Laravel Pint。

另外，社区维护的 Laravel Idea PhpStorm 插件提供了各种有用的 IDE 扩展，包括代码生成，Eloquent 语法补全，验证规则补全等等。

下一步

现在你已经创建了你的 Laravel 项目，你可能在想下一步该学什么。首先，我们强烈建议通过阅读以下文档来了解 Laravel 的工作方式：

你如何使用 Laravel 也会决定你的下一步。 Laravel 有多种使用方式，下面我们将探索框架的两个主要用例。

[！注意]
是第一次使用 Laravel 吗？请查看 Laravel Bootcamp 可让你实际操作 Laravel 框架并带你构建第一个 Laravel 应用程序。

Laravel 全栈框架

Laravel 可以作为一个全栈框架。全栈框架意味着你将使用 Laravel 将请求路由到你的应用程序，并通过 Blade 模板或像 Inertia 这样的单页应用混合技术来渲染你的前端。这是使用 Laravel 框架最常见的方式，在我们看来，这也是使用 Laravel 最高效的方式。

如果你打算使用 Laravel 进行全栈开发，你可能想查看我们的前端开发文档、路由文档、视图文档或 Eloquent ORM。此外，你可能会对学习像 Livewire 和 Inertia 这样的社区包感兴趣。这些包允许你将 Laravel 用作全栈框架，同时享受单页 JavaScript 应用程序提供的许多 UI 好处。

如果你使用 Laravel 作为全栈框架，我们也强烈建议你学习如何使用 Vite 编译应用程序的 CSS 和 JavaScript 。

[技巧]
如果你想尽快构建你的应用程序，请查看我们的官方应用程序入门工具包。

Laravel API 后端

Laravel 也可以作为 JavaScript 单页应用程序或移动应用程序的 API 后端。例如，你可以使用 Laravel 作为 Next.js 应用程序的 API 后端。在这种情况下，你可以使用 Laravel 为你的应用程序提供身份验证和数据存储/检索，同时还可以利用 Laravel 的强大服务，例如队列、电子邮件、通知等。

如果这是你计划使用 Laravel 的方式，你可能需要查看我们关于路由，Laravel Sanctum 和 Eloquent ORM 的文档。