主题
安装指南
认识 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 应用已轻松扩展至每月处理数亿请求。
需极致扩展？Laravel Cloud 等平台让您的 Laravel 应用几近无限扩展。
社区框架
Laravel 融合 PHP 生态中最优包，为您提供最强大且开发者友好的框架。此外，来自全球的数千才华横溢的开发者为框架贡献力量。谁知道呢，或许您也会成为 Laravel 贡献者。
创建 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.4)"shell
# 以管理员身份运行...
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'))shell
/bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.4)"运行上述命令后，请重启终端会话。若需更新通过 php.new 安装的 PHP、Composer 和 Laravel 安装器，可在终端重新运行该命令。
若已安装 PHP 和 Composer，可通过 Composer 安装 Laravel 安装器：
shell
composer global require laravel/installerNOTE
欲体验功能齐全的图形化 PHP 安装与管理，请查看 Laravel Herd。
创建应用
安装 PHP、Composer 和 Laravel 安装器后，您即可创建新 Laravel 应用。Laravel 安装器将提示您选择偏好的测试框架、数据库及入门套件：
shell
laravel new example-app应用创建完成后，可使用 dev Composer 脚本启动 Laravel 本地开发服务器、队列工作进程及 Vite 开发服务器：
shell
cd example-app
npm install && npm run build
composer run dev开发服务器启动后，您的应用可在浏览器中通过 http://localhost:8000 访问。接下来，您可迈向 Laravel 生态的下一步。当然，您或需配置数据库。
NOTE
若想在开发 Laravel 应用时抢占先机，可考虑使用我们的入门套件。Laravel 入门套件为新应用提供后端与前端认证脚手架。
初始配置
Laravel 框架的所有配置文件存放于 config 目录。每项配置均有文档说明，您可自由浏览文件，熟悉可用选项。
Laravel 开箱即用几乎无需额外配置，您可立即开始开发！然而，您或需查看 config/app.php 文件及其文档，其中包含如 url 和 locale 等选项，您可根据应用需求调整。
基于环境的配置
因许多 Laravel 配置选项值可能因应用运行于本地还是生产服务器而异，许多重要配置值通过应用根目录的 .env 文件定义。
您的 .env 文件不应提交至应用源码控制，因各开发者或服务器可能需不同环境配置。此外，若入侵者访问您的源码仓库，暴露敏感凭据将构成安全风险。
NOTE
欲了解更多关于 .env 文件及基于环境的配置，请查看完整的配置文档。
数据库与迁移
创建 Laravel 应用后，您或需在数据库中存储数据。默认情况下，应用的 .env 配置文件指定 Laravel 将使用 SQLite 数据库。
应用创建期间，Laravel 为您生成了 database/database.sqlite 文件，并运行了必要的迁移以创建应用数据库表。
若偏好使用 MySQL 或 PostgreSQL 等其他数据库驱动，可更新 .env 配置文件以使用相应数据库。例如，若使用 MySQL，可如此更新 .env 文件中的 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 migrateNOTE
若在 macOS 或 Windows 上开发并需本地安装 MySQL、PostgreSQL 或 Redis，可考虑使用 Herd Pro。
目录配置
Laravel 应始终从为 Web 服务器配置的“Web 目录”根目录提供服务。不应尝试从“Web 目录”的子目录提供 Laravel 应用，否则可能暴露应用中的敏感文件。
使用 Herd 进行本地安装
Laravel Herd 是一个为 macOS 和 Windows 打造的极速本地 Laravel 和 PHP 开发环境。Herd 包含开发 Laravel 所需的一切，包括 PHP 和 Nginx。
安装 Herd 后，您即可开始 Laravel 开发。Herd 提供命令行工具，包括 php、composer、laravel、expose、node、npm 和 nvm。
> [Herd Pro](https://herd.laravel.com/#plans) 为 Herd 增添强大功能，如创建和管理本地 MySQL、Postgres 和 Redis 数据库，以及本地邮件查看和日志监控。
macOS 上的 Herd
若在 macOS 上开发，可从 Herd 网站 下载 Herd 安装器。安装器自动下载最新 PHP 版本，并配置您的 Mac 始终后台运行 Nginx。
macOS 版 Herd 使用 dnsmasq 支持“停靠”目录。任何位于停靠目录的 Laravel 应用将自动由 Herd 服务。默认情况下，Herd 在 ~/Herd 创建停靠目录，您可通过目录名在 .test 域名访问其中的任何 Laravel 应用。
安装 Herd 后，使用 Herd 附带的 Laravel CLI 是创建新 Laravel 应用的最快方式：
shell
cd ~/Herd
laravel new my-app
cd my-app
herd open当然，您可通过系统托盘中的 Herd 菜单打开 Herd UI，管理停靠目录及其他 PHP 设置。
欲了解更多关于 Herd 的信息，请查看 Herd 文档。
Windows 上的 Herd
可从 Herd 网站 下载 Windows 版 Herd 安装器。安装完成后，启动 Herd 以完成入门流程并首次访问 Herd UI。
Herd UI 可通过左键单击系统托盘中的 Herd 图标访问。右键打开快速菜单，提供日常所需的所有工具。
安装期间，Herd 在您的主目录 %USERPROFILE%\Herd 创建“停靠”目录。任何位于停靠目录的 Laravel 应用将自动由 Herd 服务，您可通过目录名在 .test 域名访问其中的任何 Laravel 应用。
安装 Herd 后，使用 Herd 附带的 Laravel CLI 是创建新 Laravel 应用的最快方式。启动 Powershell 并运行以下命令：
shell
cd ~\Herd
laravel new my-app
cd my-app
herd open欲了解更多关于 Herd 的信息，请查看 Windows 版 Herd 文档。
使用 Sail 进行 Docker 安装
我们希望无论您偏好何种操作系统，开始使用 Laravel 都无比简单。因此，您有多种选择在本地机器上开发和运行 Laravel 应用。虽您或稍后探索这些选项，Laravel 提供 Sail，一个使用 Docker 运行 Laravel 应用的内置解决方案。
Docker 是一个工具，可在小型轻量“容器”中运行应用和服务，这些容器不会干扰本地机器的已安装软件或配置。您无需在本地配置或设置复杂的开发工具，如 Web 服务器和数据库。开始只需安装 Docker Desktop。
Laravel Sail 是一个轻量级命令行界面，用于与 Laravel 默认 Docker 配置交互。Sail 为构建基于 PHP、MySQL 和 Redis 的 Laravel 应用提供绝佳起点，无需 Docker 经验。
NOTE
已熟谙 Docker？无须担心！Sail 的一切皆可通过 Laravel 附带的 docker-compose.yml 文件定制。
macOS 上的 Sail
若在 Mac 上开发且已安装 Docker Desktop，可使用简单终端命令创建新 Laravel 应用。例如，在名为“example-app”的目录中创建新应用，可在终端运行：
shell
curl -s "https://laravel.build/example-app" | bash当然，您可将 URL 中的“example-app”改为任何名称，仅需确保应用名仅含字母、数字、破折号和下划线。Laravel 应用目录将在您执行命令的目录内创建。
Sail 安装可能需数分钟，以在本地构建应用容器。
应用创建后，导航至应用目录并启动 Laravel Sail。Sail 提供简单的命令行界面与 Laravel 默认 Docker 配置交互：
shell
cd example-app
./vendor/bin/sail up应用 Docker 容器启动后，运行应用的数据库迁移：
shell
./vendor/bin/sail artisan migrate最后，您可在浏览器中通过 http://localhost 访问应用。
NOTE
欲继续了解 Laravel Sail，请查看其完整文档。
Windows 上的 Sail
在 Windows 上创建新 Laravel 应用前，请确保安装 Docker Desktop。接着，确保已安装并启用 Windows 子系统 Linux 2 (WSL2)。WSL 让您在 Windows 10 上原生运行 Linux 二进制文件。有关安装和启用 WSL2 的信息，见微软的开发者环境文档。
NOTE
安装并启用 WSL2 后，确保 Docker Desktop 已配置为使用 WSL2 后端。
随后，您即可创建首个 Laravel 应用。启动 Windows Terminal，为 WSL2 Linux 系统开启新终端会话。接着，使用简单终端命令创建新应用。例如，在名为“example-app”的目录中创建新应用，可运行：
shell
curl -s https://laravel.build/example-app | bash您可将 URL 中的“example-app”改为任何名称，确保应用名仅含字母、数字、破折号和下划线。Laravel 应用目录将在您执行命令的目录内创建。
Sail 安装可能需数分钟，以在本地构建应用容器。
应用创建后，导航至应用目录并启动 Laravel Sail：
shell
cd example-app
./vendor/bin/sail up应用 Docker 容器启动后，运行应用的数据库迁移：
shell
./vendor/bin/sail artisan migrate最后，您可在浏览器中通过 http://localhost 访问应用。
NOTE
欲继续了解 Laravel Sail，请查看其完整文档。
在 WSL2 中开发
当然，您需能修改 WSL2 安装中创建的 Laravel 应用文件。为此，我们推荐使用微软的 Visual Studio Code 编辑器及其一手远程开发扩展。
安装这些工具后，可通过 Windows Terminal 从应用根目录执行 code . 命令打开任何 Laravel 应用。
Linux 上的 Sail
若在 Linux 上开发且已安装 Docker Compose，可使用简单终端命令创建新 Laravel 应用。
首先，若使用 Linux 版 Docker Desktop，执行以下命令。若不使用 Docker Desktop，可跳过此步：
shell
docker context use default然后，在名为“example-app”的目录中创建新应用，可运行：
shell
curl -s https://laravel.build/example-app | bash您可将 URL 中的“example-app”改为任何名称，确保应用名仅含字母、数字、破折号和下划线。Laravel 应用目录将在您执行命令的目录内创建。
Sail 安装可能需数分钟，以在本地构建应用容器。
应用创建后，导航至应用目录并启动 Laravel Sail：
shell
cd example-app
./vendor/bin/sail up应用 Docker 容器启动后，运行应用的数据库迁移：
shell
./vendor/bin/sail artisan migrate最后，您可在浏览器中通过 http://localhost 访问应用。
NOTE
欲继续了解 Laravel Sail，请查看其完整文档。
选择 Sail 服务
通过 Sail 创建新 Laravel 应用时，可使用 with 查询字符串变量选择在新应用的 docker-compose.yml 文件中配置的服务。可用服务包括 mysql、pgsql、mariadb、redis、valkey、memcached、meilisearch、typesense、minio、selenium 和 mailpit：
shell
curl -s "https://laravel.build/example-app?with=mysql,redis" | bash若未指定所需服务，将配置默认堆栈：mysql、redis、meilisearch、mailpit 和 selenium。
可通过在 URL 中添加 devcontainer 参数，指示 Sail 安装默认 Devcontainer：
shell
curl -s "https://laravel.build/example-app?with=mysql,redis&devcontainer" | bashIDE 支持
开发 Laravel 应用时，您可自由选择任何代码编辑器；然而，PhpStorm 为 Laravel 及其生态提供广泛支持，包括 Laravel Pint。
此外，社区维护的 Laravel Idea PhpStorm 插件提供多种实用 IDE 增强功能，如代码生成、Eloquent 语法补全、验证规则补全等。
若使用 Visual Studio Code (VS Code)，官方 Laravel VS Code 扩展 现已可用。此扩展将 Laravel 专用工具直接集成至 VS Code 环境，提升生产力。
下一步
创建 Laravel 应用后，您或疑惑接下来学什么。首先，我们强烈建议通过阅读以下文档熟悉 Laravel 的运作：
您想如何使用 Laravel 将决定接下来的旅程。Laravel 有多种使用方式，我们将在下文探索框架的两种主要用例。
Laravel 作为全栈框架
Laravel 可作为全栈框架。“全栈”意指您将使用 Laravel 路由应用请求，并通过 Blade 模板 或如 Inertia 的单页应用混合技术渲染前端。这是使用 Laravel 框架最常见的方式，我们认为也是最高效的方式。
若计划如此使用 Laravel，您或需查看关于前端开发、路由、视图 或 Eloquent ORM 的文档。此外，您可能对社区包如 Livewire 和 Inertia 感兴趣。这些包让您将 Laravel 用作全栈框架，同时享受单页 JavaScript 应用提供的诸多 UI 优势。
若将 Laravel 用作全栈框架，我们亦强烈建议学习如何使用 Vite 编译应用的 CSS 和 JavaScript。
NOTE
若想抢先构建应用，请查看我们的官方应用入门套件。
Laravel 作为 API 后端
Laravel 亦可作为 JavaScript 单页应用或移动应用的 API 后端。例如，您可将 Laravel 用作 Next.js 应用的 API 后端。在此情境中，您可使用 Laravel 提供认证 及数据存储/检索，同时利用 Laravel 的强大服务，如队列、邮件、通知等。
若计划如此使用 Laravel，您或需查看关于路由、Laravel Sanctum 和 Eloquent ORM 的文档。