Laravel 框架安裝與配置完整教學（含環境需求、伺服器設定）

Laravel 是優雅、富表達力的 PHP Web 框架，採用 MVC 架構、Composer 依賴管理、Artisan 指令列工具、Eloquent ORM、Blade 模板引擎等現代化組件。本文涵蓋從環境準備、安裝、核心配置到伺服器部署的完整流程。

系統環境需求

• PHP ≥ 8.1（Laravel 10+），建議 8.2+
• 擴展：OpenSSL、PDO、Mbstring、Tokenizer、XML、Ctype、JSON、BCMath、Fileinfo、Redis（可選）
• 資料庫：MySQL 5.7+/8.0、PostgreSQL 9.6+、SQLite、SQL Server
• Web 伺服器：Nginx + PHP-FPM（推薦）、Apache + mod_php
• Composer 2.x
• Node.js + NPM（前端資產編譯，Vite）

安裝專案

# 方式 1：Composer create-project（推薦）
composer create-project laravel/laravel my-app "10.*"

# 方式 2：Laravel Installer（全域安裝後）
laravel new my-app

cd my-app
php artisan serve  # 開發伺服器 https://127.0.0.1:8000

核心配置檔解析（config/ 目錄）

app.php：應用核心設定

'debug' => env('APP_DEBUG', false),      // 生產環境必須 false
'url' => env('APP_URL', 'https://localhost'),
'timezone' => 'Asia/Taipei',              // 時區
'locale' => 'zh_TW',                      // 語系
'fallback_locale' => 'en',
'key' => env('APP_KEY'),                  // 32 字元金鑰，php artisan key:generate
'cipher' => 'AES-256-CBC',
'providers' => [...],                     // 服務提供者
'aliases' => [...],                       // Facade 別名

database.php：資料庫連線

'default' => env('DB_CONNECTION', 'mysql'),
'connections' => [
    'mysql' => [
        'driver' => 'mysql',
        'host' => env('DB_HOST', '127.0.0.1'),
        'port' => env('DB_PORT', '3306'),
        'database' => env('DB_DATABASE', 'laravel'),
        'username' => env('DB_USERNAME', 'root'),
        'password' => env('DB_PASSWORD', ''),
        'charset' => 'utf8mb4',
        'collation' => 'utf8mb4_unicode_ci',
        'prefix' => '',
        'strict' => true,
        'engine' => 'InnoDB',
    ],
    // pgsql, sqlite, sqlsrv 同樣支援
],

環境配置（.env）

APP_NAME=Laravel
APP_ENV=local          # local, production, testing
APP_KEY=base64:xxx...
APP_DEBUG=true
APP_URL=https://localhost

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

CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_CONNECTION=sync

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

環境偵測（bootstrap/app.php）

$app->detectEnvironment(function () {
    return $_ENV['APP_ENV'] ?? 'production';
});

Web 伺服器配置

Nginx（推薦）

server {
    listen 80;
    server_name example.com;
    root /var/www/my-app/public;  # 必須指向 public/

    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Apache（.htaccess 已內建於 public/）

<VirtualHost *:80>
    DocumentRoot /var/www/my-app/public
    ServerName example.com
    <Directory /var/www/my-app/public>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

部署檢查清單

1. composer install --optimize-autoloader --no-dev
2. php artisan config:cache、route:cache、view:cache
3. php artisan migrate --force
4. npm run build（Vite 編譯前端資產）
5. 設定 storage/、bootstrap/cache/ 可寫權限（www-data）
6. 啟用 OPcache、JIT（PHP 8.1+）
7. 配置 Supervisor 管理 Queue Worker：php artisan queue:work --sleep=3 --tries=3
8. 排程器：Crontab 加入 * * * * * php /path/artisan schedule:run

常見問題排查

遵循標準安裝與部署流程，Laravel 專案即可穩定上線並享受生態系豐富套件帶來的開發效率提升。