安装

认识 Laravel

Laravel 是一个具有表现力和优雅语法的 Web 应用框架。一个 Web 框架为创建你的应用提供了结构和起点，让你可以专注于创造令人惊叹的作品，而我们会处理那些细节。

Laravel 致力于提供出色的开发者体验，同时提供强大的功能，如全面的依赖注入、表现力强大的数据库抽象层、队列和定时任务、单元和集成测试等。

无论你是刚接触 PHP Web 框架，还是拥有多年经验，Laravel 都是一个能随你成长的框架。我们将帮助你迈出作为 Web 开发者的第一步，或者在你提升技能的过程中提供助力。我们迫不及待地想看到你所构建的东西。

刚接触 Laravel？查看 Laravel Bootcamp，我们将带你亲身体验框架，帮助你构建你的第一个 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 应用

安装 PHP 和 Laravel 安装器

在创建第一个 Laravel 应用之前，确保你的本地机器上已经安装了 PHP、Composer 和 Laravel 安装器。此外，你还需要安装 Node 和 NPM 或 Bun，以便编译应用的前端资源。

如果你还没有在本地机器上安装 PHP 和 Composer，以下命令将在 macOS、Windows 或 Linux 上安装 PHP、Composer 和 Laravel 安装器：

macOS
Windows PowerShell
Linux

/bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.4)"

# Run as administrator...
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://php.new/install/windows/8.4'))

/bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.4)"

在运行上述命令后，你应该重启终端会话。要在通过 php.new 安装 PHP、Composer 和 Laravel 安装器后进行更新，你可以在终端中重新运行命令。

如果你已经安装了 PHP 和 Composer，你可以通过 Composer 安装 Laravel 安装器：

composer global require laravel/installer

要获得功能齐全的图形化 PHP 安装和管理体验，可以尝试 Laravel Herd。

创建一个应用

在安装了 PHP、Composer 和 Laravel 安装器之后，你就可以开始创建新的 Laravel 应用程序了。Laravel 安装器将提示你选择首选的 测试框架、数据库 和 起始套件(starter kit)：

laravel new example-app

应用程序创建完成后，你可以使用 dev Composer 脚本启动 Laravel 的本地开发服务器、队列工作进程和 Vite 开发服务器：

cd example-app
npm install && npm run build
composer run dev

启动开发服务器后，你的应用程序将可以通过浏览器访问： http://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 以外的数据库，您需要创建数据库并运行应用程序的数据库迁移：

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 数据库的能力，以及本地邮件查看和日志监控功能。

Herd 在 macOS 上

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

macOS 上的 Herd 使用 dnsmasq 来支持 “停放” 目录。任何位于停放(parked)目录中的 Laravel 应用程序将自动由 Herd 提供服务。默认情况下，Herd 会在 ~/Herd 目录下创建一个停放目录，您可以通过目录名称在 .test 域名下访问该目录中的任何 Laravel 应用程序。

安装 Herd 后，创建新 Laravel 应用程序的最快方式是使用与 Herd 捆绑在一起的 Laravel CLI：

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

当然，您也可以通过 Herd 的 UI 管理您的停放目录和其它 PHP 设置，该 UI 可以通过系统托盘中的 Herd 菜单打开。

您可以通过查看 Herd 文档来了解更多关于 Herd 的信息。

Herd 在 Windows 上

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

Herd UI 可以通过左键单击 Herd 的系统托盘图标来访问。右键单击会打开快速菜单，提供您日常使用的所有工具。

在安装过程中，Herd 会在您的主目录中创建一个 “停放” 目录，路径为 %USERPROFILE%\Herd。任何位于停放目录中的 Laravel 应用程序将自动由 Herd 提供服务，您可以通过目录名称在 .test 域名下访问该目录中的任何 Laravel 应用程序。

安装完 Herd 后，创建新 Laravel 应用程序的最快方式是使用与 Herd 捆绑在一起的 Laravel CLI。要开始使用，请打开 Powershell 并运行以下命令：

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

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

使用 Docker 安装 Sail

我们希望无论您选择哪种操作系统，都能尽可能轻松地开始使用 Laravel。因此，有多种选项可以在本地机器上开发和运行 Laravel 应用程序。虽然您可以在以后探索这些选项，但 Laravel 提供了 Sail，这是一个内置的解决方案，用于通过 Docker 运行您的 Laravel 应用程序。

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

Laravel Sail 是一个轻量级的命令行界面，用于与 Laravel 的默认 Docker 配置进行交互。Sail 提供了一个很好的起点，让您可以在不需要 Docker 经验的情况下使用 PHP、MySQL 和 Redis 来构建 Laravel 应用程序。

已经是 Docker 专家了？别担心！Sail 的一切都可以通过 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

最后，您可以在浏览器中访问应用程序，地址是：http://localhost。

要继续学习更多关于 Laravel Sail 的内容，请查看其完整文档。

Sail 在 Windows 上

在您的 Windows 机器上创建一个新的 Laravel 应用程序之前，请确保安装了 Docker Desktop。接下来，您需要确保启用并安装了 Windows Subsystem for Linux 2（WSL2）。WSL 允许您在 Windows 10 上本地运行 Linux 二进制可执行文件。关于如何安装和启用 WSL2 的信息，请参考微软的开发环境文档。

安装并启用 WSL2 后，您还需要确保 Docker Desktop 配置为使用 WSL2 后端。

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

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

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

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

cd example-app

./vendor/bin/sail up

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

./vendor/bin/sail artisan migrate

最后，您可以在浏览器中访问应用程序，地址是： http://localhost 。

要继续学习更多关于 Laravel Sail 的内容，请查看其完整文档。

在 WSL2 中开发

当然，您需要能够修改在 WSL2 安装中创建的 Laravel 应用程序文件。为此，我们建议使用微软的 Visual Studio Code 编辑器以及他们的远程开发第一方扩展。

安装好这些工具后，您可以通过在应用程序根目录中执行 code . 命令，在 Windows Terminal 中打开任何 Laravel 应用程序。

Sail 在 Linux 上

如果您在 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

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

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

cd example-app

./vendor/bin/sail up

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

./vendor/bin/sail artisan migrate

最后，您可以在浏览器中访问应用程序，地址是： 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 来路由请求并通过 Blade 模板或像 Inertia 这样的单页面应用混合技术来渲染前端。这是使用 Laravel 框架的最常见方式，也是我们认为最具生产力的方式。

如果这是您计划使用 Laravel 的方式，您可能需要查看我们的前端开发、路由、视图或 Eloquent ORM 的相关文档。此外，您可能会对学习社区包（如 Livewire 和 Inertia）感兴趣。这些包让您在享受单页面 JavaScript 应用提供的许多 UI 优势的同时，仍然可以将 Laravel 作为全栈框架使用。

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

如果您想在构建应用程序时获得更多帮助，可以查看我们的一些官方应用程序启动套件。

Laravel API 后端

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

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

需要帮助快速搭建您的 Laravel 后端和 Next.js 前端吗？Laravel Breeze 提供了一个 API 堆栈和 Next.js 前端实现，您可以在几分钟内开始使用。