Infrastructure on kenji.blog

Hyper-V vs WSL2：Windows 上的虛擬化技術比較

Sun, 13 Sep 2026 07:00:00 +0900

1. 簡介：Windows 中虛擬化的演進

在過去的幾十年裡，Windows 平台上的虛擬化技術經歷了巨大的演進。過去，第三方 Type 2 Hypervisor（例如 VMware Workstation 或 VirtualBox）曾是主流，但自從微軟在 Windows Server 2008 中引入「Hyper-V」以來，Type 1 Hypervisor 也被內建於作為桌面作業系統的 Windows 10/11 中。

近年來，在開發者中最受矚目的是「WSL2 (Windows Subsystem for Linux 2)」。有別於 WSL1 依賴系統呼叫的轉換 (translation)，WSL2 採用了應用 Hyper-V 技術的「輕量級公用程式虛擬機 (Lightweight Utility VM)」，實現了完全的 Linux 相容性與飛躍性的效能提升。

本文將針對這兩項強大的虛擬化技術——功能齊全的「Hyper-V」與專注於開發者體驗的「WSL2」，就其架構、效能（CPU、記憶體、磁碟 I/O）、網路設定，以及最適合的使用案例，伴隨深度的技術細節進行徹底的比較與解說。

2. Hypervisor 的基礎理論與架構比較

要理解虛擬化技術，不可或缺的是 Hypervisor（虛擬機器監視器: VMM）的類型分類。

2.1. Type 1 與 Type 2 Hypervisor 的差異

Hypervisor 是一個抽象化硬體存取，並允許多個作業系統（客體作業系統）在單一實體機器上同時執行的軟體層。

Type 1（裸機型）: 直接在硬體上執行。不存在主機作業系統的概念（嚴格來說可能存在具有特權的管理作業系統），擁有極低的額外負擔 (overhead)，提供高效能與安全性。例如：Hyper-V、VMware ESXi、Xen。
Type 2（主機型）: 作為主機作業系統（例如 Windows 或 macOS）上的應用程式執行。所有的硬體存取都必須經過主機作業系統，因此額外負擔較大。例如：VMware Workstation、Oracle VirtualBox。

Windows 的 Hyper-V 是純粹的 Type 1 Hypervisor。啟用 Hyper-V 後，實際上使用者平常操作的 Windows 作業系統本身，也會改在一個被稱為「根分割區 (Root Partition)」的特殊虛擬機器中運作。

2.2. Hyper-V 的架構細節

Hyper-V 的架構採用微核心設計，並基於被稱為分割區 (Partition) 的邏輯隔離單位。

graph TD
A["硬體 (CPU, RAM, 磁碟, NIC)"] --> B["Windows Hypervisor (Ring -1)"]
B --> C["根分割區 (Windows OS)"]
B --> D["子分割區 1 (Windows VM)"]
B --> E["子分割區 2 (Linux VM)"]
C --> F["VMBus (虛擬機器匯流排)"]
D --> F
E --> F
C --> G["VID (虛擬化基礎架構驅動程式)"]
C --> H["VMWP.exe (工作處理程序)"]

Windows Hypervisor: 在 CPU 最高特權層級的狀態（Ring -1 或 VMX Root Mode）下運作，僅負責記憶體的分配與 CPU 的排程。不包含裝置驅動程式。
根分割區 (Root Partition): 運作主機 Windows 作業系統的分割區。擁有所有的裝置驅動程式，並直接控制硬體。同時提供管理子分割區的功能（例如 WMI 提供者或 VMWP.exe 等）。
子分割區 (Child Partition): 運作客體作業系統的分割區。不允許直接存取硬體，而是透過被稱為「VMBus」的邏輯記憶體共用匯流排，向根分割區傳送 I/O 請求（綜合 I/O / Synthetic I/O）。

2.3. WSL2 與 Lightweight Utility VM 的機制

WSL2 利用了與 Hyper-V 相同的 Type 1 Hypervisor 基礎技術，但使用的是被稱為「虛擬機器平台 (Virtual Machine Platform: VMP)」的子集功能，與全功能的 Hyper-V 虛擬機器不同。

WSL2 所採用的「輕量級公用程式虛擬機 (Lightweight Utility VM)」，完全排除了傳統 VM 所擁有的舊有硬體模擬（例如虛擬 BIOS 或虛擬主機板等）。

graph TD
A["Windows 主機作業系統 (使用者空間)"]
B["NTFS 檔案系統"]
C["9P 協定伺服器 (Plan 9)"]
D["輕量級公用程式虛擬機 (Linux 核心)"]
E["ext4.vhdx (虛擬磁碟)"]
F["Linux 使用者空間 (WSL2 發行版)"]
A --> C
C -->| 跨作業系統檔案共用 | D
D --> E
D --> F

WSL2 最大的特色在於啟動速度快以及與主機作業系統的無縫整合。不到幾秒鐘內即可啟動 Linux 核心，並且透過 Plan 9 的 9P 網路檔案系統協定來存取 Windows 端的檔案系統 (NTFS)。

3. 效能徹底分析：運算資源與 I/O

虛擬機器的效能可以表示為 CPU、記憶體及磁碟 I/O 等各個元件的額外負擔總和。

3.1. CPU 與內容切換額外負擔

Hyper-V 與 WSL2 均使用了硬體輔助虛擬化 (Intel VT-x / AMD-V)。CPU 指令基本上以原生速度執行，但在執行特權指令或進行 I/O 處理時會發生稱為「VM Exit」的中斷，並向 Hypervisor 進行內容切換。

此時的 CPU 額外負擔 $T_{overhead}$ 可以用以下的數學模型來表示：

$$ T_{overhead} = \sum_{i=1}^{N} (t_{vm\_exit} + t_{hypercall\_process} + t_{vm\_entry}) $$

在此：

$N$: 單位時間內發生 VM Exit 的次數
$t_{vm\_exit}$: 從客體切換至 Hypervisor 的時間
$t_{hypercall\_process}$: 透過 VMBus 進行 I/O 處理或中斷的處理時間
$t_{vm\_entry}$: 從 Hypervisor 返回至客體的時間

WSL2 因為沒有舊有模擬，所以 $t_{hypercall\_process}$ 被極度優化並保持在極小的值。因此，在純粹的 CPU 運算（例如編譯核心或機器學習模型的推論）方面，與裸機環境相比，效能下降程度也控制在幾個百分比以內。

3.2. 記憶體分配的機制

在記憶體管理方法上，兩者有著明確的設計理念差異。

Hyper-V (Dynamic Memory): 根分割區會根據客體 VM 的記憶體需求，動態地分配與回收記憶體。然而，在客體作業系統內被保留作為分頁快取的記憶體，除非系統資源緊缺，否則通常很難被釋放。
WSL2 (動態記憶體回收): WSL2 擁有獨特的機制，會定期將 Linux VM 內不再需要的記憶體（包含快取）返還 (Reclaim) 給 Windows 主機。早期的 WSL2 曾經有 Linux 的分頁快取耗盡 Windows 記憶體的問題（Vmmem 處理程序肥大化），但目前已透過核心修補程式獲得改善。

3.3. 磁碟 I/O 特性（VHDX vs ext4.vhdx）

在虛擬機器效能中最容易成為瓶頸的就是磁碟 I/O。

I/O 的延遲 $L_{total}$ 的計算方式如下：

$$ L_{total} = L_{guest\_fs} + L_{vmbus} + L_{host\_fs} + L_{physical\_disk} $$

在 Hyper-V 的情況：一般的 Hyper-V 客體使用 VHDX 格式的虛擬磁碟。從客體作業系統內的檔案系統（ext4 或 NTFS）發出的 I/O 請求，會通過 VMBus 的區塊裝置儲存驅動程式 (storvsc)，並在 Windows 端的 NTFS 上作為對 VHDX 檔案的存取來處理。

在 WSL2 的情況： WSL2 的 Linux 發行版運作於建立在專用的 ext4.vhdx 檔案內的原生 ext4 檔案系統之上。在 Linux 內部的檔案操作（例如 ~ 目錄內），可發揮與上述 Hyper-V 同等的原生效能。然而，當從 WSL2 的 Linux 存取 Windows 端的檔案（如 /mnt/c/ 等）時，或者反向操作時，處理方式則有很大的差異。這種跨 OS 存取會使用 9P (Plan 9 File System Protocol)。

$$ L_{cross\_os} = L_{9p\_client} + L_{socket\_transfer} + L_{9p\_server} + L_{ntfs} $$

透過這個 9P 協定的存取，其序列化處理的額外負擔非常大，在需要大量讀寫小檔案的用途中（例如：在 Windows 端目錄下的 Node.js 專案執行 npm install 或 Git 操作），效能會顯著下降（有時會產生 10 倍以上的延遲）。因此，使用 WSL2 時，務必將專案檔案放置在 Linux 的原生檔案系統（~/ 目錄下），這是基本鐵則。

4. 網路結構：NAT、Default Switch、Bridged

網路功能的彈性是 Hyper-V 與 WSL2 的一大差異。

4.1. WSL2 的網路 (NAT 基礎)

WSL2 的網路預設為使用了 Hyper-V 虛擬交換器技術的「NAT（網路位址轉換）」架構。 Linux VM 會自動被分配與 Windows 主機不同的私有 IP 位址（例如：172.20.x.x）。系統內建了從 Windows 主機透過 localhost 轉發至 WSL2 內啟動的服務（連接埠）的機制，開發者可以在不需特別意識網路的情況下測試網頁伺服器等。

近年來，WSL2 在預覽版中引入了稱為「Mirrored 模式」的新網路模式。這提升了對 IPv6 的支援與 VPN 連線的相容性（可透過 .wslconfig 進行設定）。

4.2. Hyper-V 的虛擬交換器 (Virtual Switch)

Hyper-V 能夠建立企業級的高階網路架構。透過「虛擬交換器管理員」，主要提供 3 種模式：

外部 (External): 將主機機器的實體 NIC 綁定至虛擬交換器，讓客體 VM 直接加入實體網路（橋接連線）。VM 會從 DHCP 伺服器取得與實體網路相同子網路的 IP。
內部 (Internal): 僅允許主機作業系統與 VM 之間，以及 VM 彼此之間的通訊。無法直接連線至外部網路。
私人 (Private): 僅允許 VM 彼此之間的通訊，阻斷與主機作業系統的通訊。用於建立隔離的驗證環境。

4.3. 透過 PowerShell 建立進階的 Hyper-V 網路

在開發或測試環境中，如果想為 VM 建立自訂的 NAT 網路，可以使用 PowerShell 進行詳細的控制。以下是建立內部虛擬交換器，並在其中設定 NAT 以提供 VM 網際網路存取的指令碼範例。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


# 1. 建立內部虛擬交換器
$SwitchName = "HyperV-NatSwitch"
New-VMSwitch -SwitchName $SwitchName -SwitchType Internal

# 2. 在主機端的虛擬 NIC 設定 IP 位址 (作為閘道器的 IP)
$GatewayIP = "192.168.100.1"
$NetPrefix = 24
$InterfaceAlias = "vEthernet ($SwitchName)"
New-NetIPAddress -IPAddress $GatewayIP -PrefixLength $NetPrefix -InterfaceAlias $InterfaceAlias

# 3. 設定 NAT 網路
$NatName = "HyperV-NatNetwork"
$NatSubnet = "192.168.100.0/24"
New-NetNat -Name $NatName -InternalIPInterfaceAddressPrefix $NatSubnet

# 確認用命令
Get-NetNat

透過此設定，藉由手動將指定的 Hyper-V 客體設定為 192.168.100.x 的 IP 與閘道器 192.168.100.1，即可建立能經由主機與外部通訊的專屬 NAT 網段。

5. 使用案例與實用的選擇指南

根據至今為止對於架構與效能差異的了解，我們將定義在何種情況下應採用哪種技術。

5.1. 應選擇 WSL2 的情境

WSL2 是專為「提升開發者生產力」而設計的。最適合以下用途：

網頁開發與雲端原生開發: 使用 Docker Desktop（WSL2 後端）或 Podman 的容器開發。
使用 Linux 專用工具: 日常使用 bash、grep、awk、sed，或是 Linux 平台的 GCC 或 Clang 編譯器時。
GUI 應用程式 (WSLg): 想在 Windows 桌面環境上無縫執行 Linux 的 X11/Wayland 應用程式時。
機器學習與 AI 開發: 利用 GPU 穿透功能（NVIDIA CUDA on WSL）來進行 TensorFlow 或 PyTorch 的高速訓練。

注意事項: 如果想對核心進行細微的客製化，或是要建立強烈依賴 systemd 的複雜服務（目前雖已支援 systemd，但預設為停用或受限）時，可能會受到限制。

5.2. 應選擇 Hyper-V 的情境

Hyper-V 的目的在於「基礎架構的虛擬化與完全隔離」。在以下用途中將是必不可少的：

執行 Windows VM: 當需要將不同版本的 Windows（如 Windows Server 或舊版 Windows 10 等）作為測試環境執行時。
巢狀虛擬化 (Nested Virtualization): 想在虛擬機器中進一步執行虛擬機器（Hyper-V 或 KVM）時。這對於基礎設施工程師的驗證環境是不可或缺的。
進階網路需求: 需要嚴格控制網路架構時，例如外部橋接連線（加入同一個 LAN）、VLAN 標記、指派多個 NIC 等。
快照（檢查點）: 儲存 VM 在特定時間點的狀態，並能隨時瞬間還原的功能。對於軟體的破壞性測試或惡意軟體分析等非常有用。
固定的資源分配: 想嚴格固定 CPU 核心數或記憶體量，將對主機作業系統的影響降至最低時。

6. 基於數學模型的 I/O 吞吐量探討 (附錄)

身為系統工程師，在釐清兩者的 I/O 效能極限時，理論上掌握吞吐量 $S$ 與區塊大小 $B$ 的關係是很重要的。

資料傳輸的吞吐量 $S$ 為單位時間內的資料傳輸量，其模型如下：

$$ S(B) = \frac{B}{L_{setup} + \frac{B}{R_{max}}} $$

$B$: 區塊大小 (Bytes)
$L_{setup}$: 伴隨 I/O 請求的設定與內容切換而來的固定延遲
$R_{max}$: 複製或裝置傳輸中硬體的最大頻寬

在透過 WSL2 的 9P 協定存取檔案時，這個 $L_{setup}$ 會變得非常大（因為 Socket 通訊與協定的序列化/反序列化）。因此，當區塊大小 $B$ 較小（大量讀寫數 KB 左右的小檔案）時，分母中的 $L_{setup}$ 影響將佔主導地位，吞吐量 $S$ 會急遽下降。相反地，透過 Hyper-V 的 VMBus 進行 VHDX 存取時，由於 $L_{setup}$ 已被最佳化至接近硬體中斷的程度，所以即使是小規模的區塊也能維持高 IOPS。

這個數學現實成為了「在 WSL2 中絕對不能將專案檔案放在 Windows 端」這項最佳實踐的邏輯依據。

7. 總結：共存的兩種虛擬化技術

Hyper-V 與 WSL2 並不是哪一方比較優秀的問題，而是**「目的不同的兩種解決方案」**。

WSL2 打破了 Windows 這個作業系統的框架，是為了將 Linux 的生態系統無縫且高速地傳遞到 Windows 使用者手中而生的「最佳整合工具」。稱其為開發者專用的終極 CLI 環境一點也不為過。
Hyper-V 則是將企業資料中心培育出的強大隔離性與管理能力帶入桌面的「正統 Hypervisor」。在網路建構、Windows 作業系統測試、基礎設施環境模擬等方面無可匹敵。

在現代的 Windows 環境中，這兩項技術並不是勢均力敵的競爭者，而是在同一個 VM 平台上完美共存。透過根據用途適材適所地運用，Windows 將會成為世界上最強大且具彈性的工程工作站吧。

使用 Docker 建構可重現本地開發環境的步驟

Sun, 13 Sep 2026 01:00:00 +0900

1. 前言：擺脫「在我的環境裡明明就能跑」

在軟體開發的現場，因為開發者之間環境不同而導致的「在我的環境裡明明就能跑（It works on my machine）」這個問題，長久以來一直是讓許多專案浪費時間的要因。作業系統的差異、已安裝語言的版本、函式庫的相依性、全域安裝工具的衝突等，本地環境總是暴露在「狀態不確定性」之中。

能從根本解決這些課題的，就是以 Docker 為首的容器技術，以及 Infrastructure as Code (IaC) 的典範。透過將本地開發環境容器化，可實現在作業系統層級的隔離，並使環境本身能與程式碼庫一起進行版本控制。

本文將運用 Docker、Docker Compose 以及 VSCode DevContainers，為您徹底解說建構**「無論是誰、在何時、用哪台機器啟動，都能獲得分毫不差的相同狀態之可重現本地開發環境」**的步驟，以及其背後深層的技術機制，並會適時穿插數理角度的探討。

2. Infrastructure as Code (IaC) 與容器技術的契合度

IaC 的原則與在本地環境的應用

Infrastructure as Code (IaC) 是一種透過機器可讀的定義檔，而非手動流程來管理基礎設施設定與配置（Provisioning）的方法。IaC 的核心原則包含以下要素：

宣告式方法 (Declarative Approach)：定義「最終應該是什麼狀態」，而非「如何改變狀態」。
冪等性 (Idempotency)：無論執行多少次腳本，都能保證始終得到相同的結果（狀態）。
版本控制 (Version Control)：基礎設施的狀態會作為程式碼儲存於 Git 等版本控制系統 (VCS) 中，從而得以追蹤變更歷史與進行同儕審查（Peer Review）。

在本地開發環境中實踐 IaC，意味著使用 Dockerfile、docker-compose.yml 及 devcontainer.json 來將開發環境「應有的樣貌」程式碼化。如此一來，即便是新加入團隊的成員，只需複製（Clone）儲存庫並敲擊一個指令，就能實現立即開始開發的入職（Onboarding）體驗。

支撐容器技術的核心功能

容器技術與虛擬機器（VM）等 Hypervisor 類型的虛擬化不同，它是一種共享主機作業系統核心（Kernel）同時將行程隔離（Isolation）的輕量級虛擬化技術。為了實現這一點，主要利用了 Linux 核心的以下功能：

Namespaces（命名空間）：為每個行程提供系統資源（PID、網路、掛載點、使用者等）的獨立視圖。
Cgroups (Control Groups, 控制群組)：對行程可使用的實體資源（CPU、記憶體、磁碟 I/O 等）進行限制與分配。
UnionFS (Union File System, 聯合檔案系統)：將多個目錄樹（層）透明地疊加起來，呈現為單一檔案系統的技術。Docker 的映像檔分層便是依賴此技術。

讓我們來思考資源限制的數學模型。假設主機的總記憶體容量為 $M_{\text{total}}$，並假設在主機上執行的 $n$ 個容器的記憶體限制為 $m_i$。考量主機作業系統及其他行程所消耗的基礎記憶體 $M_{\text{os}}$，系統穩定運作的必要條件可以用以下不等式表示：

$$ \sum_{i=1}^{n} m_i \le M_{\text{total}} - M_{\text{os}} $$

透過利用 Cgroups 嚴格定義每個容器的 $m_i$，即使特定容器發生記憶體洩漏（Memory Leak），也能防止 OOM (Out Of Memory) Killer 導致其他容器或整個主機系統崩潰。

3. 高效的 Dockerfile 設計：將多階段建置發揮到極致

打造可重現環境的第一步，是設計用來定義應用程式執行環境的 Dockerfile。在此將以 Python（FastAPI）為例，解說活用**多階段建置（Multi-stage Build）**的安全且輕量的 Dockerfile 最佳實踐。

多階段建置是在單一 Dockerfile 中使用多個 FROM 指令，將建置環境（包含編譯器與開發工具的龐大環境）與執行環境（僅包含必要產物的輕量環境）分離的手法。

實戰 Python FastAPI 用 Dockerfile

以下程式碼是結合了使用 Poetry 進行相依性管理與多階段建置的進階 Dockerfile 範例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


# ---------------------------------------------------------
# Stage 1: Builder (建置環境)
# ---------------------------------------------------------
FROM python:3.11-slim AS builder

# 設定必要的環境變數
ENV PYTHONUNBUFFERED=1 \
 PYTHONDONTWRITEBYTECODE=1 \
 POETRY_VERSION=1.6.1 \
 POETRY_HOME="/opt/poetry" \
 POETRY_VIRTUALENVS_IN_PROJECT=true \
 POETRY_NO_INTERACTION=1

# 安裝相依套件
RUN apt-get update && apt-get install -y --no-install-recommends \
 curl build-essential && \
 curl -sSL https://install.python-poetry.org | python3 - && \
 apt-get clean && rm -rf /var/lib/apt/lists/*

ENV PATH="$POETRY_HOME/bin:$PATH"

WORKDIR /app

# 複製並安裝相依性檔案
COPY pyproject.toml poetry.lock ./
RUN poetry install --no-root --only main

# ---------------------------------------------------------
# Stage 2: Runtime (執行環境)
# ---------------------------------------------------------
FROM python:3.11-slim AS runtime

ENV PYTHONUNBUFFERED=1 \
 PYTHONDONTWRITEBYTECODE=1 \
 PATH="/app/.venv/bin:$PATH"

# 建立最小權限的非特權使用者
RUN groupadd -r appuser && useradd -r -g appuser appuser

WORKDIR /app

# 僅從 builder 複製虛擬環境（相依性）
COPY --from=builder --chown=appuser:appuser /app/.venv /app/.venv

# 複製應用程式程式碼
COPY --chown=appuser:appuser ./src /app/src

# 切換至非特權使用者
USER appuser

# 容器啟動時的預設指令
ENTRYPOINT ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

透過多階段建置評估映像檔大小的數學分析

假設單一階段建置的映像檔大小為 $S_{\text{single}}$，套用多階段建置後的映像檔大小為 $S_{\text{multi}}$。大小縮減率 $R$ 可透過以下公式計算：

$$ R = \left( 1 - \frac{S_{\text{multi}}}{S_{\text{single}}} \right) \times 100 \ (\%) $$

例如，$S_{\text{single}}$ 包含了作業系統的基礎映像檔（約 110MB）、開發用套件（如 gcc 等約 150MB）、Poetry 本體（約 40MB）、專案的相依函式庫（約 80MB）與原始碼（約 5MB），總計為 385MB。另一方面，$S_{\text{multi}}$ 僅將相依函式庫（80MB）與原始碼（5MB）複製到基礎映像檔（110MB）中，總計為 195MB。

$$ R = \left( 1 - \frac{195}{385} \right) \times 100 \approx 49.35\% $$

如上所述，藉由導入多階段建置，可以將映像檔大小縮減約一半。映像檔大小的縮減，能直接帶來縮短從 Registry 提取 (Pull) 的時間、節省磁碟空間，以及透過縮小攻擊面（Attack Surface）來提升安全性的好處。

4. 使用 Docker Compose 進行多容器的編排 (Orchestration)

在現代的 Web 應用程式開發中，Web 伺服器、資料庫、快取伺服器等多個元件協同運作的微服務架構已經非常普遍。為了在本地環境集中管理這些元件，我們使用 docker-compose.yml。

本次我們將在本地建置由「Web (FastAPI)」、「Database (PostgreSQL)」、「Cache (Redis)」構成的三層式架構系統。

架構圖（Mermaid）

下圖是展示本地機器中各個容器、網路以及 Volume 關係的區塊圖。

graph TD
User["主機機器 (瀏覽器/curl)"] -->|Localhost:8000| Web["FastAPI Web 容器"]
subgraph "Docker Bridge Network (app-network)"
Web -->|Port 5432| DB["PostgreSQL 容器"]
Web -->|Port 6379| Redis["Redis 容器"]
end
DB --> Volume1["具名 Volume (postgres_data)"]
Redis --> Volume2["具名 Volume (redis_data)"]
HostDir["主機原始碼 (./src)"] -.->|Bind Mount| Web

docker-compose.yml 的實作與詳細解說

以下展示足以應對實務環境建置的穩健 docker-compose.yml 範例。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63


version: '3.8'

services:
 web:
 build:
 context: .
 target: runtime
 container_name: dev_web
 ports:
 - "8000:8000"
 volumes:
 - ./src:/app/src:ro  # 以唯讀方式掛載主機程式碼（用於熱重載）
 environment:
 - DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
 - REDIS_URL=redis://redis:6379/0
 env_file:
 - .env
 depends_on:
 db:
 condition: service_healthy
 redis:
 condition: service_started
 networks:
 - app-network
 command: ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

 db:
 image: postgres:15-alpine
 container_name: dev_db
 ports:
 - "5432:5432"
 environment:
 POSTGRES_USER: postgres
 POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
 POSTGRES_DB: ${POSTGRES_DB}
 volumes:
 - postgres_data:/var/lib/postgresql/data
 networks:
 - app-network
 healthcheck:
 test: ["CMD-SHELL", "pg_isready -U postgres -d ${POSTGRES_DB}"]
 interval: 5s
 timeout: 5s
 retries: 5

 redis:
 image: redis:7-alpine
 container_name: dev_redis
 ports:
 - "6379:6379"
 volumes:
 - redis_data:/data
 networks:
 - app-network
 command: ["redis-server", "--appendonly", "yes"]

volumes:
 postgres_data:
 redis_data:

networks:
 app-network:
 driver: bridge

Volume 與資料的持久化

容器原則上是「無狀態（Stateless）」且「短暫（Ephemeral）」的存在。一旦銷毀容器，內部的資料也會隨之消失。為了保留資料庫的資料或快取，必須將主機機器的檔案系統區域掛載到容器中。

綁定掛載 (Bind Mount)：上述 web 服務中的 ./src:/app/src:ro 即屬此類。將主機的特定目錄直接對映到容器內。用於讓本地程式碼的編輯能立即反映在容器中（熱重載）。從安全的觀點來看，附加 :ro (Read-Only, 唯讀) 選項，以防止容器端修改主機的原始碼是最佳實踐。
具名 Volume (Named Volume)：如 postgres_data 與 redis_data 屬此類。這是 Docker 內部（例如 /var/lib/docker/volumes/）管理的區域，擁有比綁定掛載更優秀的 I/O 效能，並能吸收作業系統之間檔案系統的差異。對於資料庫的持久化，務必使用此方式。

網路 (Networking) 與服務探索 (Service Discovery)

Docker Compose 預設會為每個專案建立專屬的橋接網路。即是上述的 app-network。屬於同一個網路的容器之間，可以使用「服務名稱（例：db, redis）」作為主機名稱來進行名稱解析（DNS 解析），而不是使用 IP 位址。例如，從 Web 容器能以 postgresql://postgres:password@db:5432/mydb 這個 URL 存取資料庫。藉由這種方式，無論是在本地環境還是正式環境，都能透過環境變數透明地切換連線目標。

健康檢查 (Healthcheck) 與啟動順序控制

depends_on 指令會控制容器的啟動順序，但若僅指定 depends_on，Web 容器會在「DB 容器已啟動」的階段跟著啟動。由於實際上 DB 的初始化程序（PostgreSQL 的行程啟動或資料表準備）完成需要數秒鐘，因此這可能會導致來自 Web 容器的 DB 連線發生錯誤。為了防止這種情況發生，可以透過定義 healthcheck 並指定 condition: service_healthy，確保「DB 已處於能接受連線請求的狀態」後，再啟動 Web 容器。

5. 環境變數管理與安全性 (.env)

將資料庫密碼或 API 金鑰等機密資訊寫死（Hardcoding）在 docker-compose.yml 中，是絕對要避免的反模式（Anti-pattern）。取而代之的是，應使用環境變數檔案 .env 來注入這些值。

在專案根目錄建立 .env 檔案。

1
2
3
4


# .env 檔案 (為了不被 Git 納入版控，請將其加入 .gitignore)
POSTGRES_PASSWORD=supersecretpassword
POSTGRES_DB=devdb
API_SECRET_KEY=dev_secret_key_12345

Docker Compose 預設會讀取執行目錄下的 .env 檔案，並將 YAML 檔案中的 ${VAR_NAME} 佔位符展開。透過這個方法，我們就能針對本地、測試（Staging）及正式等不同環境，安全地管理不同的設定值，而無須修改基礎設施的程式碼。

6. VSCode DevContainers 帶來的終極開發體驗

到目前為止，我們已經建構了使用 Docker 的穩健後端環境。然而，我們還能更進一步。使用 VSCode DevContainers (Remote - Containers) 功能，便能將編輯器（VSCode）本身的後端執行於容器內部。

這樣一來，本地機器連 Python 或 Node.js 都不需要安裝，從 Linter（flake8/eslint）與格式化工具（black/prettier），到 IDE 的擴充功能，全都可以定義在程式碼庫中讓團隊所有人共享。

devcontainer.json 設定

在專案根目錄建立 .devcontainer 目錄，並將設定檔放置其中。

.devcontainer/devcontainer.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


{
 "name": "Python FastAPI Dev Environment",
 "dockerComposeFile": ["../docker-compose.yml"],
 "service": "web",
 "workspaceFolder": "/app",
 "customizations": {
 "vscode": {
 "settings": {
 "python.defaultInterpreterPath": "/app/.venv/bin/python",
 "python.formatting.provider": "black",
 "editor.formatOnSave": true
 },
 "extensions": [
 "ms-python.python",
 "ms-python.vscode-pylance",
 "ms-python.black-formatter",
 "tamasfe.even-better-toml"
 ]
 }
 },
 "forwardPorts": [8000, 5432, 6379],
 "remoteUser": "appuser",
 "postCreateCommand": "poetry install"
}

只要將這個檔案包含在儲存庫中，在用 VSCode 開啟專案的瞬間就會顯示「Reopen in Container」的提示，只需點擊它，所有需要的容器就會啟動、擴充功能也會安裝完畢，立刻進入可以開始撰寫程式碼的狀態。這簡直是如魔法般的體驗。

7. 請求處理的時序與效能建模

我們將透過時序圖來確認所建構的本地開發環境中，Web 應用程式處理請求的生命週期，並探討其效能的數學模型。

時序圖（請求流程）

sequenceDiagram
participant Client as "瀏覽器 / VSCode"
participant Web as "FastAPI (Web)"
participant Redis as "Redis 快取"
participant DB as "PostgreSQL"
Client->>Web: "GET /api/users/123"
activate Web
Web->>Redis: "檢查 user:123 的快取"
activate Redis
alt "快取命中 (有資料)"
Redis-->>Web: "回傳快取的使用者資料"
Web-->>Client: "200 OK (快速回應)"
else "快取未命中 (無資料)"
Redis-->>Web: "Null (找不到)"
deactivate Redis
Web->>DB: "SELECT * FROM users WHERE id = 123"
activate DB
DB-->>Web: "回傳資料庫資料列"
deactivate DB
Web->>Redis: "設定 user:123 資料 (TTL: 60s)"
activate Redis
Redis-->>Web: "OK"
deactivate Redis
Web-->>Client: "200 OK (標準回應)"
end
deactivate Web

處理延遲（Latency）的數學模型

我們將針對上述系統的平均請求處理時間 $T_{\text{total}}$ 進行數學建模。將各項處理的延遲定義如下：

$T_{\text{net}}$：客戶端與 Web 容器之間的網路延遲
$T_{\text{app}}$：應用程式端的純粹處理時間（如序列化等）
$T_{\text{cache}}$：向 Redis 讀取與寫入所花費的時間
$T_{\text{db}}$：向 PostgreSQL 執行查詢所花費的時間
$p_{\text{miss}}$：快取未命中率（$0 \le p_{\text{miss}} \le 1$）

此時，平均回應時間可以透過以下期望值計算公式來表示：

$$ T_{\text{total}} = T_{\text{net}} + T_{\text{app}} + T_{\text{cache}} + p_{\text{miss}} \times (T_{\text{db}} + T_{\text{cache\_write}}) $$

在本地開發環境（Docker 內），$T_{\text{net}}$ 幾乎接近 0，但值得注意的是綁定掛載時的 I/O 效能。尤其是在 Windows/macOS 上使用 Docker Desktop 的情況下，因為主機作業系統與 VM（容器）之間的檔案共享額外開銷 (Overhead)，$T_{\text{app}}$（程式碼讀取時間等）往往會有變得龐大的趨勢。為了解決這個效能瓶頸，強烈建議利用前述的 DevContainers 將整個原始碼配置到具名 Volume 中，或是採用在 WSL2（Windows Subsystem for Linux 2）環境中原生執行 Docker 引擎的架構。

8. Docker 建置效能最佳化：分層快取 (Layer Cache) 策略

在撰寫 Dockerfile 時，是否理解「分層快取 (Layer Cache)」的機制，會讓建置時間有著戲劇性的變化。 Docker 會針對 Dockerfile 的每一個指令（如 FROM、RUN、COPY 等）建立檔案系統的差異（層次），並作為快取保留。在重新建置時，若該層未發生變更，便會重複利用快取。

重要的原則是：「從變更頻率較低的項目開始依序撰寫」。

我們來思考原始碼變更對建置時間帶來影響的模型化。假設總建置時間為 $T_{\text{build}}$，每個步驟的執行時間為 $T_{\text{layer}_i}$，快取命中有無的布林值為 $c_i \in \{0, 1\}$（命中時為 1）。

$$ T_{\text{build}} = T_{\text{init}} + \sum_{i=1}^{n} (1 - c_i) \times T_{\text{layer}_i} $$

一旦在第 $k$ 層發生快取未命中（$c_k = 0$），其後所有第 $j > k$ 層的快取也都會失效（$c_j = 0$）。

1
2
3
4


# 錯誤範例 (先複製了原始碼)
COPY ./src /app/src
COPY pyproject.toml poetry.lock ./
RUN poetry install

在上述情況下，只要修改了一行程式碼，第一個 COPY 就會發生快取未命中，導致每次都必須執行耗時的 RUN poetry install。

1
2
3
4


# 良好範例 (先進行相依性的解析)
COPY pyproject.toml poetry.lock ./
RUN poetry install
COPY ./src /app/src

只要照這樣撰寫，即使變更了原始碼，poetry install 的分層快取（$c_i = 1$）依然有效，建置時間將會從幾分鐘劇減為幾秒鐘。

9. 疑難排解與 Tips

以下列舉在操作本地環境時常遇到的問題與解決方案。

連接埠衝突錯誤 如果出現類似 Bind for 0.0.0.0:8000 failed: port is already allocated 的錯誤，表示本地機器上有其他行程正在使用該連接埠。可以透過將主機端的連接埠號碼修改為類似 ports: - "8080:8000" 來避免此問題。
磁碟空間耗盡 若長時間使用 Docker，未使用的映像檔或 Volume（Dangling Images / Volumes）會不斷累積，甚至可能佔用數十 GB 的磁碟空間。建議定期使用以下指令清理系統：
1

docker system prune -a --volumes
檔案權限問題 在 Linux 環境使用綁定掛載時，容器內建立的檔案擁有者會變成 root，有時會導致主機端無法編輯。這可以透過在 Dockerfile 中建立非特權使用者，並使其與主機作業系統自身的 UID/GID（例：1000:1000）一致來解決。

10. 結語：可重現性所帶來的開發速度提升

透過結合 Docker、Docker Compose 以及 VSCode DevContainers，便能實現「無論是誰啟動環境，都會是完全相同狀態」的穩健本地開發環境。

將 IaC 的典範引進本地環境，不僅僅是縮短了最初的環境設置時間而已。它消除了對更改基礎設施設定的擔憂，讓測試新技術堆疊變得更加容易，並能順利過渡到 CI/CD 管道等，讓整個開發週期的速度與品質都獲得飛躍性的提升。

敬請活用本文所解說的最佳實踐，如透過多階段建置將映像檔大小最佳化、使用健康檢查控制相依性，以及意識到分層快取來撰寫 Dockerfile 等，為您自己的專案也引進最棒的開發者體驗（DX: Developer Experience）吧。