Laravel 中文文档

主题

全部文档

安装 ​

认识 Laravel ​

Laravel 是一个语法富有表现力、设计优雅的 Web 应用框架。Web 框架会为你的应用提供结构和起点，让你专注于创造出色的产品，而繁琐细节则由框架来操心。

Laravel 致力于提供出色的开发体验，同时带来强大的能力，例如完善的依赖注入、富有表现力的数据库抽象层、队列与定时任务、单元测试与集成测试等。

无论你是刚接触 PHP Web 框架，还是已有多年经验，Laravel 都能陪你一起成长。我们会帮你迈出成为 Web 开发者的第一步，也会在你进阶时提供助力。我们迫不及待想看到你的作品。

为什么选择 Laravel？ ​

构建 Web 应用时可选的工具和框架很多。但我们相信，Laravel 是构建现代全栈 Web 应用的最佳选择。

渐进式框架 ​

我们喜欢把 Laravel 称为「渐进式」框架，意思是它会随着你的水平一起成长。如果你刚开始学习 Web 开发，Laravel 丰富的文档、指南和视频教程能帮你循序渐进地入门，而不会一下子被淹没。

如果你是资深开发者，Laravel 会为你提供可靠的工具，例如依赖注入、单元测试、队列、实时事件等。Laravel 专为专业级 Web 应用打磨，也能胜任企业级负载。

可扩展的框架 ​

Laravel 具备出色的扩展能力。得益于 PHP 友好的扩展特性，以及 Laravel 对 Redis 等高速分布式缓存的内置支持，横向扩展非常轻松。事实上，已有 Laravel 应用轻松扩展到每月处理数亿次请求。

需要极致扩展？像 Laravel Cloud 这样的平台，能让你的 Laravel 应用接近无限扩展。

面向 AI Agent 的框架 ​

Laravel 明确的约定和清晰的结构，使它非常适合配合 Cursor、Claude Code 等工具进行AI 辅助开发。当你让 AI agent 新增控制器时，它清楚该放在哪里；需要新迁移时，命名与文件位置也是可预期的。这种一致性减少了 AI 在更松散框架中常遇到的猜测成本。

除了文件组织，Laravel 富有表现力的语法和全面的文档，也为 AI agent 提供了生成准确、地道代码所需的上下文。Eloquent 关联、表单请求、中间件等特性都遵循 agent 能够稳定理解并复现的模式。最终生成的代码更像资深 Laravel 开发者所写，而不是拼凑的通用 PHP 片段。

想进一步了解为何 Laravel 适合 AI 辅助开发，请参阅面向 Agent 的开发文档。

社区驱动的框架 ​

Laravel 汇聚了 PHP 生态中优秀的包，提供稳健且对开发者友好的框架体验。此外，全球成千上万的优秀开发者已为框架做出贡献。说不定，你也会成为 Laravel 贡献者之一。

创建 Laravel 应用 ​

使用 AI 入门 ​

如果你在使用 Claude Code 或 OpenCode 这类 AI 编程 agent，可以先给它一段提示词，在动手改项目之前先提供 Laravel 专用指引。

下面的提示词会告诉 agent 去哪里查找 Laravel 安装指引、应优先做什么，以及在你尚未做选择时如何采用合理默认值。把它粘贴给 agent 即可开始：

text
I'm building a new Laravel application.

Fetch and follow the instructions from https://laravel.com/for/agents. Treat the returned Markdown as the source of truth for how to install and set up Laravel in this session.

agent 读完指引后，应一步步引导你，并使安装过程与 Laravel 的默认约定保持一致。

安装 PHP 与 Laravel 安装器 ​

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

如果本机还没有 PHP 和 Composer，可用下列命令在 macOS、Windows 或 Linux 上安装 PHP、Composer 和 Laravel 安装器：

shell
/bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.5)"
shell
# 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.5'))
shell
/bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.5)"

执行以上任一命令后，请重新打开终端会话。若之后要通过 php.new 更新 PHP、Composer 和 Laravel 安装器，在终端中再次运行该命令即可。

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

shell
composer global require laravel/installer

INFO

若需要功能完整、带图形界面的 PHP 安装与管理体验，请参阅 Laravel Herd。

创建应用 ​

安装好 PHP、Composer 和 Laravel 安装器后，就可以创建新的 Laravel 应用了：

shell
laravel new example-app

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

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

开发服务器启动后，可在浏览器访问 http://localhost:8000。接下来可以继续探索 Laravel 生态。当然，你也可能想先配置数据库并运行必要的迁移。

INFO

如果希望开发时有个更好的起点，可考虑使用我们的起步套件。Laravel 起步套件会为新应用提供前后端认证脚手架。

初始配置 ​

Laravel 框架的全部配置文件都存放在 config 目录中。每个选项都有说明，不妨浏览这些文件，熟悉可用配置。

开箱即用时，Laravel 几乎不需要额外配置，你可以直接开始开发。不过，建议先看看 config/app.php 及其说明，其中有 url、locale 等可能需要按应用调整的选项。

基于环境的配置 ​

许多配置项在本地与生产环境中的值可能不同，因此不少重要配置写在应用根目录的 .env 文件中。

.env 不应提交到版本控制：不同开发者或服务器可能需要不同环境配置；若仓库被入侵，敏感凭据也会随之暴露。

INFO

关于 .env 与基于环境的配置，详见完整的配置文档。

数据库与迁移 ​

应用创建好后，通常需要把数据存进数据库。默认情况下，.env 会配置 Laravel 使用 SQLite。

创建应用时，Laravel 已为你生成 database/database.sqlite，并运行了必要迁移以创建数据表。

若更想使用 MySQL 或 PostgreSQL 等驱动，可修改 .env。例如使用 MySQL 时，可这样配置 DB_* 变量：

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

若未使用 SQLite，需要自行创建数据库，并运行应用的数据库迁移：

shell
php artisan migrate

INFO

若在 macOS 或 Windows 上开发，并需要本地安装 MySQL、PostgreSQL 或 Redis，可考虑使用 Herd Pro 或 DBngin。

目录配置 ​

Laravel 应始终从 Web 服务器配置的「网站根目录」对外提供服务，不要从该目录的子目录托管 Laravel 应用，否则可能暴露应用中的敏感文件。

使用 Herd 安装 ​

Laravel Herd 是面向 macOS 与 Windows 的高速原生 Laravel / PHP 开发环境，内置开始 Laravel 开发所需的一切，包括 PHP 和 Nginx。

安装 Herd 后即可开始用 Laravel 开发。Herd 提供 php、composer、laravel、expose、node、npm、nvm 等命令行工具。

INFO

Herd Pro 在 Herd 基础上增加了更多能力，例如创建和管理本地 MySQL、Postgres、Redis，以及本地邮件查看与日志监控。

在 macOS 上使用 Herd ​

若在 macOS 上开发，可从 Herd 官网下载安装程序。安装程序会自动下载最新版 PHP，并配置 Mac 在后台持续运行 Nginx。

macOS 版 Herd 使用 dnsmasq 支持「停靠」目录。停靠目录中的 Laravel 应用会由 Herd 自动托管。默认停靠目录为 ~/Herd，可用目录名通过 .test 域名访问其中的应用。

安装 Herd 后，最快的方式是使用随 Herd 附带的 Laravel CLI 创建应用：

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

当然，也可以通过系统托盘中的 Herd 菜单打开 UI，管理停靠目录及其他 PHP 设置。

更多信息见 Herd 文档。

在 Windows 上使用 Herd ​

可在 Herd 官网下载 Windows 安装包。安装完成后启动 Herd，完成引导流程并首次进入 Herd UI。

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

安装过程中，Herd 会在用户目录创建停靠目录 %USERPROFILE%\Herd。其中的 Laravel 应用会由 Herd 自动托管，并通过目录名以 .test 域名访问。

安装后，最快的方式是使用随 Herd 附带的 Laravel CLI。打开 PowerShell 并运行：

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

更多信息见 Windows 版 Herd 文档。

IDE 支持 ​

开发 Laravel 应用时可自由选择编辑器。Laravel LSP 提供面向框架的编辑器支持，包括代码补全、悬停信息、诊断、文档链接、跳转到定义，以及对 Laravel 与 Blade 的快速修复。

可通过 Composer 全局安装 Laravel LSP，并确保 Composer 的全局 vendor/bin 已加入 PATH：

shell
composer global require laravel/lsp

若偏好轻量可扩展编辑器，VS Code 或 Cursor 配合官方 Laravel VS Code 扩展，可提供语法高亮、代码片段、Artisan 集成以及自动的 Laravel LSP 支持。另有面向 Sublime Text 与 Zed 的官方扩展。其他兼容语言服务器的编辑器（如 Neovim、OpenCode）请参考 Laravel LSP 仓库 的说明。

若需要更全面、稳健的 Laravel 支持，可看看 JetBrains 的 PhpStorm。其内置 Laravel 支持涵盖 Blade、Eloquent 模型/路由/视图/翻译/组件的智能补全，以及强大的代码生成与项目导航。

若想要云端开发体验，Firebase Studio 可让你直接在浏览器中使用 Laravel，几乎零配置，方便在任意设备上开始构建。

Laravel 与 AI ​

Laravel Boost 能连接 AI 编程 agent 与 Laravel 应用，为 agent 提供 Laravel 专用上下文、工具与指南，从而生成更准确、贴合版本且符合约定的代码。

在应用中安装 Boost 后，AI agent 可使用 15+ 个专用工具，例如了解已安装的包、查询数据库、检索 Laravel 文档、读取浏览器日志、生成测试，以及通过 Tinker 执行代码。

此外，Boost 还为 agent 提供超过 17,000 条向量化的 Laravel 生态文档，并针对你安装的包版本，因此指导会贴合项目实际版本。

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

安装 Laravel Boost ​

Boost 可用于运行 PHP 8.1+ 的 Laravel 10、11、12、13 应用。首先作为开发依赖安装：

shell
composer require laravel/boost --dev

安装后运行交互式安装程序：

shell
php artisan boost:install

安装程序会自动检测 IDE 与 AI agent，让你按项目需要选择功能。Boost 会尊重现有项目约定，默认不强加风格规则。

INFO

了解更多请见 GitHub 上的 Laravel Boost 仓库。

添加自定义 AI 指南 ​

若要为 Boost 补充自定义 AI 指南，把 .blade.php 或 .md 文件放到应用的 .ai/guidelines/* 目录。运行 boost:install 时会自动一并纳入。

下一步 ​

应用创建完成后，你可能想知道接下来学什么。建议先阅读以下文档，熟悉 Laravel 的工作方式：

你打算如何使用 Laravel，也会影响接下来的路径。用法有很多种，下面介绍两种主要场景。

将 Laravel 用作全栈框架 ​

Laravel 可用作全栈框架。这里的「全栈」指：用 Laravel 路由请求，并通过 Blade 模板 或 Inertia 这类前后端混合方案渲染前端。这是最常见的用法，在我们看来也是最高效的用法。

若计划这样使用，可阅读前端开发、路由、视图或 Eloquent ORM 文档。也可以了解社区包 Livewire 与 Inertia，它们让你在全栈使用 Laravel 的同时，也能享受不少单页应用的 UI 优势。

若将 Laravel 用作全栈框架，也强烈建议学习如何用 Vite 编译 CSS 与 JavaScript。

INFO

若希望更快起步，可查看官方应用起步套件。

将 Laravel 用作 API 后端 ​

Laravel 也可作为 JavaScript 单页应用或移动应用的 API 后端。例如为 Next.js 提供 API。此时可用 Laravel 负责认证与数据存取，并继续使用队列、邮件、通知等能力。

若计划这样使用，可阅读路由、Laravel Sanctum 与 Eloquent ORM 文档。