Skip to content

fbiceo/dev-container-tutorial

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
.devcontainer
.devcontainer
 
 
client
client
 
 
db
db
 
 
server
server
 
 
.env.example
.env.example
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
docker-compose.yml
docker-compose.yml
 
 
package.json
package.json
 
 
vite.config.js
vite.config.js
 
 

Repository files navigation

🐳 Dev Container 完整教學

在 Antigravity 中使用 Dev Container 進行網站開發，不同機器、相同環境。

本教學帶你從零開始設定 Dev Container 開發環境，搭配一個完整的全端範例應用（Node.js + Express + Vite + PostgreSQL）。

📋 目錄

  1. 什麼是 Dev Container？
  2. 為什麼需要 Dev Container？
  3. 前置需求
  4. 專案結構說明
  5. 快速開始
  6. 配置檔案詳解
  7. Docker Compose 多服務架構
  8. 在 Antigravity 中使用 Dev Container
  9. 團隊協作最佳實踐
  10. 常見問題排解
  11. 延伸學習

什麼是 Dev Container？

Dev Container（Development Container）是一種利用 Docker 容器 來定義完整開發環境的方式。

簡單來說，你把整個開發環境（語言執行環境、工具、資料庫、設定）都「裝進一個容器裡」，任何人在任何機器上打開這個專案，都會得到 完全相同的開發環境。

┌─────────────────────────────────────┐
│          你的電腦（Host）              │
│                                     │
│  ┌───────────────────────────────┐  │
│  │      Dev Container            │  │
│  │                               │  │
│  │  ✅ Node.js 20                │  │
│  │  ✅ PostgreSQL 16             │  │
│  │  ✅ VS Code 擴充套件          │  │
│  │  ✅ ESLint / Prettier         │  │
│  │  ✅ Git 工具                   │  │
│  │  ✅ 你的專案程式碼              │  │
│  │                               │  │
│  └───────────────────────────────┘  │
│                                     │
│  Docker Desktop 負責管理             │
└─────────────────────────────────────┘

為什麼需要 Dev Container？

😫 沒有 Dev Container 時…

問題 痛點
「在我電腦可以跑啊」 每個人的 Node.js 版本不同，npm 版本不同，資料庫版本不同
新人入職要裝環境 花一整天安裝各種工具，踩各種坑
Windows vs Mac vs Linux 同一份程式碼在不同 OS 跑出不同結果
多專案環境衝突 A 專案需要 Node 18，B 專案需要 Node 20
環境「髒掉了」 本機裝了一堆全域套件，不知道哪個影響了哪個

🎉 有了 Dev Container

解決方案 效果
環境即程式碼 環境定義寫在設定檔裡，跟程式碼一起版控
一鍵啟動 Reopen in Container → 完整環境就緒
跨平台一致 Windows、Mac、Linux 都跑同一個 Linux 容器
完全隔離 每個專案有自己的環境，互不干擾
新人友善 Clone → 打開 → 自動進入開發環境，5 分鐘就能開工

前置需求

開始之前，確保你的電腦安裝了以下工具：

1. Docker Desktop

Docker Desktop 是容器的引擎。

安裝完成後，確認 Docker 正在執行：

docker --version
# 應該看到類似: Docker version 27.x.x

2. Visual Studio Code

3. Dev Containers 擴充套件

在 VS Code 中安裝：

  • 打開 VS Code
  • 按 Ctrl+Shift+X（擴充套件面板）
  • 搜尋 Dev Containers
  • 安裝 Microsoft 發行的 Dev Containers 擴充套件（或安裝整個 Remote Development 擴充套件包）

專案結構說明

dev-container-tutorial/
│
├── .devcontainer/               # 🐳 Dev Container 配置
│   ├── devcontainer.json        #    主要配置檔（環境定義）
│   └── Dockerfile               #    容器映像建置腳本
│
├── client/                      # 💻 前端程式碼
│   ├── index.html               #    HTML 頁面
│   ├── main.js                  #    前端邏輯
│   └── style.css                #    CSS 樣式
│
├── server/                      # 🖥️ 後端程式碼
│   └── index.js                 #    Express API
│
├── db/                          # 🐘 資料庫
│   └── init.sql                 #    初始化腳本
│
├── docker-compose.yml           # 🔧 多服務容器編排
├── vite.config.js               # ⚡ Vite 前端建置設定
├── package.json                 # 📦 Node.js 專案設定
├── .env.example                 # 🔐 環境變數範本
└── .gitignore                   # 🚫 Git 忽略規則

快速開始

Step 1：複製此專案

git clone <你的 repo URL>
cd dev-container-tutorial

Step 2：用 VS Code 打開專案

code .

Step 3：在 Dev Container 中打開

VS Code 偵測到 .devcontainer 資料夾後，右下角會跳出通知：

📦 Folder contains a Dev Container configuration file. Reopen folder to develop in a container?

點選 Reopen in Container。

或者你可以手動操作：

  1. 按 F1 或 Ctrl+Shift+P 開啟命令面板
  2. 輸入 Dev Containers: Reopen in Container
  3. 按 Enter

Step 4：等待容器建置

第一次啟動需要下載映像和安裝依賴，大約需要 3-5 分鐘（視網路速度）。 之後再次啟動只需要幾秒鐘。

你會看到 VS Code 左下角顯示：

><  Dev Container: Dev Container 教學環境

Step 5：啟動開發伺服器

在 VS Code 的終端機（Ctrl+`）中：

npm run dev

這會同時啟動：

Step 6：打開瀏覽器看成果

瀏覽 http://localhost:5173，你會看到書籤管理應用，頁面上會顯示：

  • 容器環境資訊（Node.js 版本、OS、記憶體等）
  • 服務健康狀態
  • 可操作的書籤 CRUD

🎉 恭喜！你已經在 Dev Container 中進行開發了！

配置檔案詳解

devcontainer.json — 核心配置

這是 Dev Container 最重要的檔案，告訴 VS Code 如何建立開發環境：

{
  // 容器名稱
  "name": "Dev Container 教學環境",

  // 使用 Docker Compose 管理多個服務
  "dockerComposeFile": "../docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",

  // VS Code 客製化：擴充套件 & 設定
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",       // ESLint 程式碼檢查
        "esbenp.prettier-vscode",        // Prettier 格式化
        "eamodio.gitlens"                // Git 增強工具
      ],
      "settings": {
        "editor.formatOnSave": true      // 存檔自動格式化
      }
    }
  },

  // Port 轉發
  "forwardPorts": [5173, 3000, 5432, 8080],

  // 容器建立後自動執行的指令
  "postCreateCommand": "npm install",

  // 容器內的使用者（不用 root）
  "remoteUser": "node",

  // Dev Container Features（擴展功能）
  "features": {
    "ghcr.io/devcontainers/features/git:1": {},
    "ghcr.io/devcontainers/features/github-cli:1": {}
  }
}

關鍵屬性說明

屬性 用途
name 容器名稱，會顯示在 VS Code 左下角
dockerComposeFile 指定 Docker Compose 檔案
service 指定要連接的服務（對應 docker-compose.yml）
workspaceFolder 容器內的工作目錄
customizations.vscode.extensions 自動安裝的 VS Code 擴充套件
customizations.vscode.settings VS Code 編輯器設定
forwardPorts 自動轉發的 Port
postCreateCommand 容器首次建立後執行的指令
postStartCommand 每次容器啟動後執行的指令
remoteUser 容器內使用的帳號
features Dev Container Features — 可組合的環境擴展

Dockerfile — 映像定義

# 基於 Microsoft 官方 Node.js 開發映像
FROM mcr.microsoft.com/devcontainers/javascript-node:20

# 安裝額外工具
RUN apt-get update && apt-get -y install \
    postgresql-client \  # 資料庫客戶端
    jq                   # JSON 處理工具

為什麼不直接用 image？

devcontainer.json 支援兩種方式指定基礎環境：

方式 何時使用
"image": "..." 官方映像就夠用、不需要額外安裝東西
"dockerFile": "Dockerfile" 需要安裝額外套件或自訂環境

本教學使用 Dockerfile 是因為我們需要安裝 PostgreSQL 客戶端工具。

Dev Container Features

Features 是可以像積木一樣組合的「環境功能模組」。不需要自己寫安裝指令，只要在 devcontainer.json 中聲明：

"features": {
  // 安裝 Git
  "ghcr.io/devcontainers/features/git:1": {},
  // 安裝 GitHub CLI
  "ghcr.io/devcontainers/features/github-cli:1": {},
  // Docker-in-Docker（容器內可以用 Docker）
  "ghcr.io/devcontainers/features/docker-in-docker:2": {}
}

常用的 Features：

Feature 用途
git Git 版本控制
github-cli GitHub 命令列工具
docker-in-docker 在容器內使用 Docker
aws-cli AWS CLI
azure-cli Azure CLI
python Python 環境
go Go 環境

📚 完整清單：https://containers.dev/features

Docker Compose 多服務架構

真實的網站開發通常需要多個服務協作。本專案使用 Docker Compose 管理三個服務：

┌─────────────────────────────────────────────┐
│              Docker Network                  │
│                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │   app    │  │    db    │  │ adminer  │  │
│  │ Node.js  │──│PostgreSQL│──│ DB GUI   │  │
│  │  :3000   │  │  :5432   │  │  :8080   │  │
│  │  :5173   │  │          │  │          │  │
│  └──────────┘  └──────────┘  └──────────┘  │
│                                              │
└─────────────────────────────────────────────┘

服務間如何通訊？

在 Docker Compose 的網路中，各服務可以用 服務名稱 互相存取：

// app 容器中連接 db 容器
const pool = new pg.Pool({
  connectionString: 'postgresql://devuser:devpass@db:5432/devdb'
  //                                              ↑↑
  //                            用服務名稱 "db" 而不是 "localhost"
});

健康檢查

docker-compose.yml 中設定了健康檢查，確保資料庫就緒後 app 才啟動：

db:
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U devuser -d devdb"]
    interval: 5s
    timeout: 5s
    retries: 5

app:
  depends_on:
    db:
      condition: service_healthy  # 等 db 通過健康檢查

資料持久化

使用 Docker Named Volume 保存資料：

volumes:
  postgres_data:   # 資料庫資料（容器重建不遺失）
  node_modules:    # Node.js 套件快取（跨平台效能最佳化）

在 Antigravity 中使用 Dev Container

什麼是 Antigravity?

Antigravity 是 Google 的 AI 輔助開發平台（Gemini Code Assist 的進階版），可以在 VS Code 中協助你寫程式、除錯、重構。

搭配 Dev Container 使用的流程

1. 打開專案 → Reopen in Container
2. Dev Container 啟動完成
3. Antigravity 擴充套件自動啟用
4. 在容器環境中直接使用 AI 輔助

技巧與注意事項

✅ 將 Antigravity 擴充套件加入 devcontainer.json

確保團隊成員都能自動擁有 AI 輔助：

"customizations": {
  "vscode": {
    "extensions": [
      // ... 其他擴充套件
      "google.gemini-code-assist"   // Antigravity / Gemini Code Assist
    ]
  }
}

✅ 在容器中使用 AI 指令

Dev Container 啟動後，你可以正常使用所有 Antigravity 功能：

  • 程式碼補全：在編輯器中正常輸入，AI 會自動建議
  • 對話：使用 Gemini 側邊面板詢問問題
  • 程式碼生成：描述需求，讓 AI 幫你生成程式碼
  • 除錯：選取錯誤訊息，請 AI 協助分析

✅ 善用 AI 建立 Dev Container 配置

你可以直接告訴 Antigravity：

「幫我建立一個 Laravel + MySQL + Redis 的 Dev Container 配置」

AI 會根據你的需求生成完整的 devcontainer.json 和相關配置。

⚠️ 注意事項

  1. 登入狀態：重建容器後可能需要重新登入 Google 帳號
  2. 網路存取：容器內需要能存取外部網路才能使用 AI 功能
  3. 效能：如果容器資源不足，AI 回應可能較慢，可在 Docker Desktop 中增加記憶體配額

團隊協作最佳實踐

1. 所有配置都提交到 Git

# 確保這些檔案都被版控
git add .devcontainer/
git add docker-compose.yml
git add .env.example    # 範本（不是 .env！）

2. 環境變數管理

# .env.example → 提交到 Git（範本）
# .env         → 不提交（包含機密資訊）

cp .env.example .env
# 然後編輯 .env 填入實際值

3. 統一 VS Code 設定

透過 devcontainer.json 中的 customizations.vscode.settings，團隊成員會自動套用相同的：

  • Tab 大小
  • 格式化規則
  • Linter 設定
  • 檔案換行符號

4. 使用 postCreateCommand 自動化

// 第一次建立容器時自動執行
"postCreateCommand": "npm install && npm run db:reset && echo '✅ 環境就緒'"

5. 文件化你的容器

在 README 中說明：

  • 需要的前置軟體
  • 可用的 npm scripts
  • 各服務的 Port 和用途
  • 常見問題與解法

常見問題排解

❓ 容器建置失敗

症狀：VS Code 卡在「Building container...」

解法：

# 1. 確認 Docker 正在執行
docker info

# 2. 嘗試清除 Docker 快取後重建
docker system prune -f

# 3. 在 VS Code 中：F1 → Dev Containers: Rebuild Container

❓ Port 衝突

症狀：Error: listen EADDRINUSE: address already in use :::3000

解法：

# 查看佔用 Port 的程序
# Windows
netstat -ano | findstr :3000

# Mac/Linux
lsof -i :3000

# 或修改 docker-compose.yml 中的 Port 映射

❓ 容器內 npm install 很慢

解法：

  1. 在 Docker Desktop 中增加 Memory（至少 4GB）
  2. 使用 Named Volume 保存 node_modules（本專案已設定）
  3. 考慮使用 .npmrc 設定國內映像源

❓ 資料庫連不上

症狀：Error: connect ECONNREFUSED 127.0.0.1:5432

解法：

# 在容器內，資料庫要用服務名稱 "db"，不是 "localhost"
# ✅ 正確：postgresql://devuser:devpass@db:5432/devdb
# ❌ 錯誤：postgresql://devuser:devpass@localhost:5432/devdb

# 檢查資料庫是否啟動
docker compose ps

❓ 檔案權限問題（Linux）

解法：

// 在 devcontainer.json 中設定
"remoteUser": "node",
"updateRemoteUserUID": true

❓ Docker Desktop 佔用太多資源

解法： 在 Docker Desktop → Settings → Resources 中調整：

  • CPUs: 建議至少 2 核
  • Memory: 建議至少 4 GB
  • Disk: 建議至少 20 GB

延伸學習

官方資源

常見技術棧的 Dev Container 配置

🐘 PHP + Laravel + MySQL 
{
  "name": "Laravel Dev",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/var/www/html",
  "customizations": {
    "vscode": {
      "extensions": [
        "bmewburn.vscode-intelephense-client",
        "onecentlin.laravel-blade"
      ]
    }
  },
  "features": {
    "ghcr.io/devcontainers/features/php:1": { "version": "8.3" },
    "ghcr.io/devcontainers/features/node:1": { "version": "20" }
  }
}
🐍 Python + Django + PostgreSQL 
{
  "name": "Django Dev",
  "image": "mcr.microsoft.com/devcontainers/python:3.12",
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "ms-python.vscode-pylance"
      ]
    }
  },
  "postCreateCommand": "pip install -r requirements.txt",
  "features": {
    "ghcr.io/devcontainers/features/node:1": { "version": "20" }
  }
}
⚛️ Next.js + TypeScript 
{
  "name": "Next.js Dev",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "bradlc.vscode-tailwindcss"
      ]
    }
  },
  "forwardPorts": [3000],
  "postCreateCommand": "npm install"
}

📁 指令速查表

指令 用途
npm run dev 同時啟動前端 + 後端
npm run dev:server 只啟動後端 API
npm run dev:client 只啟動前端 Vite
npm run db:reset 重設資料庫
F1 → Dev Containers: Reopen in Container 進入 Dev Container
F1 → Dev Containers: Rebuild Container 重建容器
F1 → Dev Containers: Reopen Folder Locally 退出 Dev Container

🐳 Built with Dev Containers — 不同機器，相同環境
Node.js + Express + Vite + PostgreSQL

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages