Laravel PHP 框架安裝與環境配置完整教學（含 .env、資料庫、時區、金鑰設定）

系統需求

• Web Server：Nginx / Apache
• PHP ≥ 7.3（Laravel 8+ 需 PHP 7.3+，Laravel 10+ 需 PHP 8.1+）
• Composer
• 資料庫：MySQL / PostgreSQL / SQLite / SQL Server
• PHP 擴展：pdo, mbstring, xml, ctype, json, bcmath, tokenizer, fileinfo, openssl

安裝 Laravel

# 方式 1：Composer create-project（指定版本）
composer create-project laravel/laravel my-app "10.*" --prefer-dist

# 方式 2：Laravel Installer（全域安裝後）
composer global require laravel/installer
laravel new my-app

目錄結構重點

my-app/
├── app/           # 應用核心代碼 (Models, Controllers, Services)
├── bootstrap/     # 應用啟動引導
├── config/        # 所有設定檔
├── database/      # 遷移、種子、工廠
├── public/        # 公開入口 (index.php, 前端資產)
├── resources/     # 視圖、語言、原始前端資源
├── routes/        # 路由定義 (web.php, api.php)
├── storage/       # 日誌、快取、上傳檔案 (需寫入權限)
├── tests/         # 測試代碼
├── vendor/        # Composer 依賴
├── .env           # 環境變數 (不納入版控)
├── .env.example   # 環境變數範本
└── artisan        # CLI 指令入口

關鍵配置檔案

1. .env 環境變數（最重要）

APP_NAME=Laravel
APP_ENV=local
APP_KEY=base64:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # php artisan key:generate 產生
APP_DEBUG=true
APP_URL=https://localhost

LOG_CHANNEL=stack
LOG_LEVEL=debug

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

BROADCAST_DRIVER=log
CACHE_DRIVER=file
FILESYSTEM_DISK=local
QUEUE_CONNECTION=sync
SESSION_DRIVER=file
SESSION_LIFETIME=120

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

2. config/app.php 核心設定

'timezone' => 'Asia/Taipei',        // 時區
'locale' => 'zh_TW',                // 語言
'fallback_locale' => 'en',
'key' => env('APP_KEY'),            // 從 .env 讀取
'cipher' => 'AES-256-CBC',
'providers' => [ /* 服務提供者 */ ],
'aliases' => [ /* Facade 別名 */ ],

3. config/database.php 資料庫設定

'default' => env('DB_CONNECTION', 'mysql'),
'connections' => [
    'mysql' => [
        'driver' => 'mysql',
        'url' => env('DATABASE_URL'),
        'host' => env('DB_HOST', '127.0.0.1'),
        'port' => env('DB_PORT', '3306'),
        'database' => env('DB_DATABASE', 'forge'),
        'username' => env('DB_USERNAME', 'forge'),
        'password' => env('DB_PASSWORD', ''),
        'unix_socket' => env('DB_SOCKET', ''),
        'charset' => 'utf8mb4',
        'collation' => 'utf8mb4_unicode_ci',
        'prefix' => '',
        'prefix_indexes' => true,
        'strict' => true,
        'engine' => null,
        'options' => extension_loaded('pdo_mysql') ? [PDO::ATTR_EMULATE_PREPARES => true] : [],
    ],
    // pgsql, sqlite, sqlsrv 等其他驅動...
],

環境偵測與多環境配置

bootstrap/app.php 中：

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

可建立 .env.local, .env.testing, .env.production 等檔案，部署時以實際環境變數 APP_ENV 切換。

常用 Artisan 指令

Nginx 虛擬主機配置範例

server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/my-app/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; # 或 127.0.0.1:9000
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_hide_header X-Powered-By;
    }

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

部署檢查清單

1. APP_ENV=production, APP_DEBUG=false
2. APP_KEY 已設定且**不外洩**
3. 資料庫憑證正確、遷移完成
4. storage/, bootstrap/cache/ 可寫入 (www-data 權限)
5. 執行 php artisan config:cache, php artisan route:cache, php artisan view:cache
6. 啟用 HTTPS、設定 HSTS、CSP 等安全標頭
7. 配置佇列 Worker (Supervisor)、排程器 (Cron)
8. 設定日誌輪轉 (logrotate)、監控 (Laravel Telescope / Sentry)