> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装

> 介绍 Laravel 的安装步骤以及 PHP 环境的搭建方法。

## 环境要求

在开始使用 Laravel 之前，你需要以下环境：

* **PHP 8.3 及以上**
* **Composer**（PHP 的包管理器）
* **Laravel Installer**（可选，但推荐）

<Info>
  编译前端资源时还需要 Node.js/npm 或 Bun。
</Info>

## 安装 PHP 与 Laravel Installer

同时安装 PHP、Composer 与 Laravel Installer 最简单的方式，是根据你的操作系统执行以下命令。

<CodeGroup>
  ```shell macOS theme={null}
  /bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.4)"
  ```

  ```powershell Windows (以管理员身份运行) theme={null}
  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 Linux theme={null}
  /bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.4)"
  ```
</CodeGroup>

执行命令后，请重启终端会话。
如果你已经安装了 PHP 和 Composer，可以只通过 Composer 安装 Laravel Installer。

```shell theme={null}
composer global require laravel/installer
```

<Tip>
  如果你希望使用图形化的 PHP 管理工具，也可以查看 [使用 Laravel Herd 安装](#使用-laravel-herd-安装)。
</Tip>

## 创建新的 Laravel 应用

准备好 PHP、Composer 与 Laravel Installer 后，就可以创建新的 Laravel 应用了。
安装器会引导你选择测试框架、数据库以及启动套件。

```shell theme={null}
laravel new example-app
```

应用创建完成后，通过 `dev` Composer 脚本启动开发服务器。

```shell theme={null}
cd example-app
npm install && npm run build
composer run dev
```

开发服务器启动后，在浏览器中访问 [http://localhost:8000](http://localhost:8000)。

<Info>
  使用启动套件时，会自动生成包含认证功能的项目脚手架。Laravel 13 提供 React、Vue、Svelte、Livewire 四种选择。
</Info>

### 启动套件的选项

执行 `laravel new` 命令时，你可以从以下启动套件中选择一种。

<AccordionGroup>
  <Accordion title="React">
    基于 [Inertia](https://inertiajs.com) 的 React 前端启动套件。采用 React 19、TypeScript、Tailwind 与 [shadcn/ui](https://ui.shadcn.com)，提供了将 SPA 与服务端路由结合的现代方案。
  </Accordion>

  <Accordion title="Vue">
    基于 [Inertia](https://inertiajs.com) 的 Vue 前端启动套件。采用 Vue Composition API、TypeScript、Tailwind 与 [shadcn-vue](https://www.shadcn-vue.com/)。
  </Accordion>

  <Accordion title="Svelte">
    基于 [Inertia](https://inertiajs.com) 的 Svelte 前端启动套件。采用 Svelte 5、TypeScript、Tailwind 与 [shadcn-svelte](https://www.shadcn-svelte.com/)。
  </Accordion>

  <Accordion title="Livewire">
    基于 [Laravel Livewire](https://livewire.laravel.com) 的启动套件。只用 PHP 就可以构建动态 UI，最适合以 Blade 模板为主的团队。采用 Tailwind 与 [Flux UI](https://fluxui.dev)。
  </Accordion>
</AccordionGroup>

<Tip>
  如果你不确定选择哪种方案，请先在[前端](/zh/frontend)中梳理 Blade、Livewire、Inertia、SPA 的差异，会更容易判断。
</Tip>

## 使用 Laravel Herd 安装

[Laravel Herd](https://herd.laravel.com) 是面向 macOS 与 Windows 的原生 Laravel / PHP 开发环境。
它可以一次性安装 PHP、Nginx 与 Laravel CLI。

### macOS

1. 从 [Herd 官网](https://herd.laravel.com)下载安装器。
2. 运行安装器后，PHP 会被自动配置。
3. `~/Herd` 目录会被设置为停靠目录（parked directory）。

```shell theme={null}
cd ~/Herd
laravel new my-app
cd my-app
herd open
```

### Windows

1. 从 [Herd 官网](https://herd.laravel.com/windows)下载 Windows 安装器。
2. 安装完成后启动 Herd，并完成引导流程。
3. `%USERPROFILE%\Herd` 会成为停靠目录。

```shell theme={null}
cd ~\Herd
laravel new my-app
cd my-app
herd open
```

## 初始配置

### 环境配置

Laravel 中许多配置项会因环境不同而变化。
因此，你需要通过应用根目录的 `.env` 文件来管理重要的配置。

<Warning>
  请不要将 `.env` 文件提交到版本控制。
  否则可能导致机密信息泄露。
</Warning>

### 数据库配置

默认情况下，Laravel 使用 SQLite。
如果要使用 MySQL 或 PostgreSQL，请修改 `.env` 文件。

```ini theme={null}
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=
```

如果使用 SQLite 之外的数据库，请运行迁移来创建数据表。

```shell theme={null}
php artisan migrate
```

## IDE 支持

<AccordionGroup>
  <Accordion title="VS Code / Cursor">
    安装官方的 [Laravel VS Code Extension](https://marketplace.visualstudio.com/items?itemName=laravel.vscode-laravel) 即可获得语法高亮、代码片段、Artisan 命令集成、Eloquent 模型智能补全等 Laravel 支持。
  </Accordion>

  <Accordion title="PhpStorm">
    [PhpStorm](https://www.jetbrains.com/phpstorm/laravel/) 对 Laravel 框架有内置支持，可对 Blade 模板、Eloquent 模型、路由、视图与翻译进行智能补全。
  </Accordion>
</AccordionGroup>

## 下一步

<Card title="目录结构" icon="folder-open" href="/zh/directory-structure">
  了解 Laravel 项目的主要目录与文件。
</Card>


## Related topics

- [Laravel Reverb](/zh/reverb.md)
- [Laravel Boost](/zh/boost.md)
- [广播](/zh/broadcasting.md)
- [Laravel Pint](/zh/pint.md)
- [Laravel Telescope](/zh/telescope.md)