Docker 開發環境建置：從零開始的完整指南

前言

「在我電腦上可以跑啊」大概是工程師最經典的一句話。Docker 可以讓這個問題徹底消失。這篇文章會教你從零開始，用 Docker 建立一個 Laravel + React 的開發環境。

為什麼要用 Docker？

環境一致性

不管是 macOS、Windows 還是 Linux，Docker 容器裡的環境都是一樣的。團隊協作時不會再有環境差異的問題。

快速部署

開發環境的配置都寫在設定檔裡，新成員只要一個指令就能啟動整個開發環境。

隔離性

不同專案可以使用不同版本的 PHP、Node.js、MySQL，互不干擾。

專案結構

project/
├── docker/
│   ├── nginx/
│   │   └── default.conf
│   └── php/
│       └── Dockerfile
├── docker-compose.yml
├── src/                    # Laravel 專案
└── .env

撰寫 Dockerfile

首先建立 PHP 的 Dockerfile：

# docker/php/Dockerfile
FROM php:8.3-fpm

# 安裝系統相依套件
RUN apt-get update && apt-get install -y \
    git \
    curl \
    libpng-dev \
    libonig-dev \
    libxml2-dev \
    zip \
    unzip

# 安裝 PHP 擴充套件
RUN docker-php-ext-install pdo_mysql mbstring exif pcntl bcmath gd

# 安裝 Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# 安裝 Node.js
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
    && apt-get install -y nodejs

# 設定工作目錄
WORKDIR /var/www/html

# 設定使用者權限
RUN groupadd -g 1000 www && \
    useradd -u 1000 -ms /bin/bash -g www www

USER www

Docker Compose 設定

# docker-compose.yml
version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: docker/php/Dockerfile
    container_name: laravel-app
    volumes:
      - ./src:/var/www/html
    networks:
      - app-network
    depends_on:
      - mysql
      - redis

  nginx:
    image: nginx:alpine
    container_name: laravel-nginx
    ports:
      - "8080:80"
    volumes:
      - ./src:/var/www/html
      - ./docker/nginx/default.conf:/etc/nginx/conf.d/default.conf
    networks:
      - app-network
    depends_on:
      - app

  mysql:
    image: mysql:8.0
    container_name: laravel-mysql
    environment:
      MYSQL_DATABASE: laravel
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_USER: laravel
      MYSQL_PASSWORD: secret
    ports:
      - "3306:3306"
    volumes:
      - mysql-data:/var/lib/mysql
    networks:
      - app-network

  redis:
    image: redis:alpine
    container_name: laravel-redis
    ports:
      - "6379:6379"
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

volumes:
  mysql-data:
    driver: local

Nginx 設定

# docker/nginx/default.conf
server {
    listen 80;
    index index.php index.html;
    root /var/www/html/public;

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

    location ~ \.php$ {
        fastcgi_pass app:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }
}

啟動開發環境

第一次啟動

# 建置並啟動所有容器
docker-compose up -d --build

# 進入 app 容器
docker-compose exec app bash

# 安裝 PHP 相依套件
composer install

# 安裝前端相依套件
npm install

# 設定環境變數
cp .env.example .env
php artisan key:generate

# 執行資料庫遷移
php artisan migrate --seed

常用指令

# 啟動容器
docker-compose up -d

# 停止容器
docker-compose down

# 查看容器狀態
docker-compose ps

# 查看 log
docker-compose logs -f app

# 執行 artisan 指令
docker-compose exec app php artisan migrate

# 執行前端開發伺服器
docker-compose exec app npm run dev

使用 Laravel Sail 簡化流程

如果你不想自己寫 Dockerfile，Laravel 官方的 Sail 是個好選擇：

# 安裝 Sail
composer require laravel/sail --dev
php artisan sail:install

# 啟動
./vendor/bin/sail up -d

# 執行指令
./vendor/bin/sail artisan migrate
./vendor/bin/sail npm install

Sail 內建了 MySQL、Redis、Mailpit 等常用服務，設定起來更方便。不過自訂彈性比較低，大型專案我還是偏好自己寫 Docker 設定。

開發環境的 .env 設定

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

REDIS_HOST=redis
REDIS_PORT=6379

CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

注意 DB_HOST 和 REDIS_HOST 要填 Docker Compose 中定義的 service 名稱，不是 localhost。

常見問題排除

權限問題

最常遇到的就是檔案權限問題，特別是 storage 和 bootstrap/cache 目錄：

docker-compose exec app chmod -R 775 storage bootstrap/cache
docker-compose exec app chown -R www:www storage bootstrap/cache

MySQL 連線失敗

確認 MySQL 容器已經完全啟動。可以加入 healthcheck：

mysql:
  image: mysql:8.0
  healthcheck:
    test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
    interval: 10s
    timeout: 5s
    retries: 3

熱更新不生效

在 vite.config.js 中加入：

export default defineConfig({
    server: {
        host: '0.0.0.0',
        hmr: {
            host: 'localhost',
        },
    },
});

結語

Docker 的學習曲線雖然比較陡，但學會之後會大幅提升開發效率。特別是接案時，可以快速建立和切換不同專案的環境，也不怕搞亂自己的電腦。建議從簡單的專案開始練習，慢慢就會上手了。