安装

认识 Laravel

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

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

无论你是 PHP Web 框架的新手还是拥有多年经验，Laravel 都是一个可以与你一起成长的框架。我们将帮助你迈出 Web 开发者的第一步，或者在你将专业技能提升到新水平时给你助力。我们迫不及待地想看到你构建的作品。

为什么选择 Laravel？

在构建 Web 应用时，你有各种各样的工具和框架可供选择。然而，我们相信 Laravel 是构建现代全栈 Web 应用的最佳选择。

渐进式框架

我们喜欢称 Laravel 为"渐进式"框架。我们的意思是，Laravel 会与你一起成长。如果你刚开始涉足 Web 开发，Laravel 丰富的文档库、指南和视频教程将帮助你在不感到不知所措的情况下学习基础知识。

如果你是高级开发者，Laravel 为你提供了强大的工具，包括依赖注入、单元测试、队列、实时事件等。Laravel 针对构建专业 Web 应用进行了精细调优，可以处理企业级工作负载。

可扩展的框架

Laravel 具有令人难以置信的可扩展性。得益于 PHP 的扩展友好特性以及 Laravel 对快速分布式缓存系统（如 Redis）的内置支持，使用 Laravel 进行水平扩展轻而易举。事实上，Laravel 应用已经可以轻松扩展到每月处理数亿次请求。

需要极致扩展？像 Laravel Cloud 这样的平台允许你以几乎无限的规模运行 Laravel 应用。

Agent 就绪的框架

Laravel 的约定式规范和良好定义的结构使其成为使用 Cursor 和 Claude Code 等工具进行 AI 辅助开发的理想框架。当你要求 AI agent 添加一个 controller 时，它确切地知道应该放在哪里。当你需要新的 migration 时，命名约定和文件位置是可预测的。这种一致性消除了在更灵活的框架中经常困扰 AI 工具的猜测工作。

除了文件组织之外，Laravel 富有表现力的语法和全面的文档为 AI agent 提供了生成准确、地道代码所需的上下文。Eloquent 关联关系、表单请求和 middleware 等功能遵循 agent 可以可靠理解和复制的模式。最终结果是 AI 生成的代码看起来像是由经验丰富的 Laravel 开发者编写的，而不是从通用 PHP 代码片段拼凑而成。

要了解更多关于为什么 Laravel 是 AI 辅助开发的完美选择，请查看我们关于 Agentic 开发的文档。

社区框架

Laravel 整合了 PHP 生态系统中最好的包，提供了最强大且开发者友好的框架。此外，来自世界各地的数千名优秀开发者为框架做出了贡献。谁知道呢，也许你也会成为 Laravel 的贡献者。

创建 Laravel 应用

安装 PHP 和 Laravel 安装器

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

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

macOS

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

Windows PowerShell

# 以管理员身份运行...
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'))

Linux

/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

NOTE

如需功能齐全的图形化 PHP 安装和管理体验，请查看 Laravel Herd。

创建应用

安装好 PHP、Composer 和 Laravel 安装器后，你就可以创建新的 Laravel 应用了。Laravel 安装器会提示你选择首选的测试框架、数据库和入门套件：

laravel new example-app

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

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

启动开发服务器后，你的应用将可以在浏览器中通过 http://localhost:8000 访问。接下来，你可以开始迈入 Laravel 生态系统的下一步。当然，你可能还想配置数据库。

NOTE

如果你想在开发 Laravel 应用时获得一个良好的起步，可以考虑使用我们的入门套件。Laravel 的入门套件为你的新 Laravel 应用提供后端和前端认证脚手架。

初始配置

Laravel 框架的所有配置文件都存储在 config 目录中。每个选项都有文档说明，因此请随意浏览这些文件并熟悉可用的选项。

Laravel 开箱即用几乎不需要额外配置。你可以自由地开始开发！不过，你可能希望查看 config/app.php 文件及其文档。它包含几个选项，如 url 和 locale，你可能希望根据你的应用进行更改。

基于环境的配置

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

你的 .env 文件不应提交到应用的源代码管理中，因为使用你应用的每个开发者/服务器可能需要不同的环境配置。此外，如果入侵者获得了对源代码仓库的访问权限，这将构成安全风险，因为任何敏感凭证都会被暴露。

NOTE

有关 .env 文件和基于环境的配置的更多信息，请查看完整的配置文档。

数据库和迁移

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

在创建应用的过程中，Laravel 为你创建了一个 database/database.sqlite 文件，并运行了必要的 migration 来创建应用的数据库表。

如果你更喜欢使用其他数据库驱动（如 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

NOTE

如果你在 macOS 或 Windows 上开发，需要在本地安装 MySQL、PostgreSQL 或 Redis，请考虑使用 Herd Pro 或 DBngin。

目录配置

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 的命令行工具。

NOTE

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

macOS 上的 Herd

如果你在 macOS 上开发，可以从 Herd 网站下载 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 UI 可以通过左键单击 Herd 的系统托盘图标来访问。右键单击可打开快捷菜单，其中包含你日常所需的所有工具。

在安装过程中，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 的信息。

IDE 支持

在开发 Laravel 应用时，你可以自由使用任何代码编辑器。如果你正在寻找轻量且可扩展的编辑器，VS Code 或 Cursor 配合官方的 Laravel VS Code 扩展提供了出色的 Laravel 支持，包括语法高亮、代码片段、Artisan 命令集成，以及针对 Eloquent 模型、路由、middleware、资源、配置和 Inertia.js 的智能自动补全。

如果需要全面而强大的 Laravel 支持，可以看看 PhpStorm，一个 JetBrains IDE。PhpStorm 内置的 Laravel 框架支持包括 Blade 模板、Eloquent 模型、路由、视图、翻译和组件的智能自动补全，以及跨 Laravel 项目的强大代码生成和导航功能。

对于寻求基于云的开发体验的用户，Firebase Studio 提供了直接在浏览器中使用 Laravel 进行构建的即时访问。无需任何设置，Firebase Studio 让你可以轻松地从任何设备开始构建 Laravel 应用。

Laravel 与 AI

Laravel Boost 是一个强大的工具，它弥合了 AI 编码 agent 与 Laravel 应用之间的差距。Boost 为 AI agent 提供 Laravel 特定的上下文、工具和指南，使它们能够生成更准确的、特定版本的、遵循 Laravel 约定的代码。

当你在 Laravel 应用中安装 Boost 后，AI agent 可以访问超过 15 个专业工具，包括了解你正在使用的包、查询数据库、搜索 Laravel 文档、读取浏览器日志、生成测试以及通过 Tinker 执行代码的能力。

此外，Boost 为 AI agent 提供了超过 17,000 条向量化的 Laravel 生态系统文档，这些文档针对你安装的包版本。这意味着 agent 可以提供针对你的项目所使用的确切版本的指导。

Boost 还包含 Laravel 维护的 AI 指南，帮助 agent 遵循框架约定、编写适当的测试，并在生成 Laravel 代码时避免常见陷阱。

安装 Laravel Boost

Boost 可以安装在运行 PHP 8.1 或更高版本的 Laravel 10、11 和 12 应用中。首先，将 Boost 作为开发依赖安装：

composer require laravel/boost --dev

安装完成后，运行交互式安装程序：

php artisan boost:install

安装程序将自动检测你的 IDE 和 AI agent，让你选择适合项目的功能。Boost 默认尊重现有的项目约定，不会强制使用固执己见的样式规则。

NOTE

要了解更多关于 Boost 的信息，请查看 GitHub 上的 Laravel Boost 仓库。

添加自定义 AI 指南

要使用你自己的自定义 AI 指南增强 Laravel Boost，请将 .blade.php 或 .md 文件添加到应用的 .ai/guidelines/* 目录中。当你运行 boost:install 时，这些文件将自动包含在 Laravel Boost 的指南中。

下一步

现在你已经创建了 Laravel 应用，你可能想知道接下来该学什么。首先，我们强烈建议通过阅读以下文档来熟悉 Laravel 的工作原理：

• 请求生命周期
• 配置
• 目录结构
• 前端
• Service Container
• Facades

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

全栈框架 Laravel

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

如果你计划这样使用 Laravel，你可能想查看我们关于前端开发、路由、视图或 Eloquent ORM 的文档。此外，你可能对学习 Livewire 和 Inertia 等社区包感兴趣。这些包允许你将 Laravel 用作全栈框架，同时享受单页 JavaScript 应用提供的许多 UI 优势。

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

NOTE

如果你想在构建应用时获得一个良好的起步，请查看我们官方的应用入门套件。

API 后端 Laravel

Laravel 也可以作为 JavaScript 单页应用或移动应用的 API 后端。例如，你可以将 Laravel 用作 Next.js 应用的 API 后端。在此场景中，你可以使用 Laravel 为应用提供认证和数据存储/检索，同时利用 Laravel 的强大服务，如队列、电子邮件、通知等。

如果你计划这样使用 Laravel，你可能想查看我们关于路由、Laravel Sanctum 和 Eloquent ORM 的文档。