> ## 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-TW/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-TW/directory-structure">
  瞭解 Laravel 專案的主要目錄與檔案。
</Card>


## Related topics

- [用 Laravel 構建 MCP 伺服器](/zh-TW/advanced/mcp-server.md)
- [什麼是 Laravel](/zh-TW/introduction.md)
- [Laravel Boost Custom Agent for PhpStorm with GitHub Copilot](/zh-TW/packages/laravel-boost-phpstorm-copilot.md)
- [建立 Boost 的自定義 Agent](/zh-TW/advanced/boost-custom-agent.md)
- [Laravel Boost Custom Agent for GitHub Copilot CLI](/zh-TW/packages/laravel-boost-copilot-cli.md)