Docker on kenji.blog

使用 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）吧。

WSL2（Windows Subsystem for Linux）的終極開發環境設定指南

Sat, 12 Sep 2026 23:00:00 +0900

在 Windows 上提供原生 Linux 開發環境的「WSL2（Windows Subsystem for Linux 2）」已成為現代軟體開發中不可或缺的工具。然而，維持預設狀態使用，與了解架構並進行適當的調校相比，兩者在效能和開發體驗上會有天壤之別。

本文將從 WSL2 核心的架構解說開始，徹底解說能將效能發揮到極致的設定、建構舒適的終端機環境、與 Docker 和 VS Code 的無縫整合，以及進階的網路設定。為了建構專業工程師所追求的「終極開發環境」，我們將以超過一萬字以上的篇幅為您詳細說明所有的步驟。

1. WSL2 的架構與自 WSL1 的進化

為了完全發揮 WSL2 的潛力，首先必須了解其內部結構。第一代 WSL（WSL1）與 WSL2 在 Windows 上執行 Linux 二進位檔案的方法有著根本上的差異。

WSL1：系統呼叫的轉換層

WSL1 採用了將 Linux 的系統呼叫即時轉換（Translation）為 Windows NT API 的機制。由於不使用虛擬機器（VM），這項作法具有資源負擔極小的優點。然而，要完全模擬檔案系統的 I/O 操作等複雜系統呼叫相當困難，特別是在執行 Node.js 的 npm install 或是 Git 的版本庫操作等處理大量小檔案的作業時，會導致效能出現絕望性的下降。

WSL2：輕量級公用程式 VM 與完整的 Linux 核心

WSL2 重新設計了架構，在利用 Hyper-V 架構子集的「輕量級公用程式 VM」 上，直接執行由 Microsoft 建置的真正 Linux 核心。這確保了系統呼叫 100% 的相容性，並透過使用採用 Linux 原生 ext4 檔案系統的虛擬磁碟（VHDX），檔案 I/O 效能與 WSL1 相比有了戲劇性的提升。

以下的 Mermaid 圖表展示了 WSL1 與 WSL2 的結構差異。

flowchart TD
subgraph "Windows 作業系統環境"
A["Windows NT 核心"]
A --> F["NTFS 檔案系統 (C: 磁碟機)"]
end
subgraph "WSL2 架構"
B["Hyper-V Hypervisor"]
B --> C["輕量級公用程式 VM"]
C --> D["Linux 核心 (Microsoft)"]
D --> E["Ubuntu 使用者空間 (glibc, bash 等)"]
D --> G["ext4 虛擬磁碟 (.vhdx)"]
end
A -.->|"Plan 9 (9P) 通訊協定網路檔案共用"| D
style B fill:#f9f,stroke:#333,stroke-width:2px
style D fill:#bbf,stroke:#333,stroke-width:2px

從這個結構中獲得的重要教訓是，「對 Linux 側的檔案（VHDX 內部）存取速度極快，但對 Windows 側的檔案（/mnt/c/）存取因為需要透過 9P 通訊協定而非常緩慢」。專案的原始碼必須一律放置於 WSL 側的主目錄（~）之下。

2. 效能的數學分析：為什麼 WSL2 這麼快？

讓我們試著使用數學模型來定量評估 WSL2 的效能提升。在軟體開發中，最耗時的操作之一就是伴隨大量檔案 I/O 的處理程序（例如：安裝函式庫或建置）。

某個處理程序的總執行時間 $T_{total}$，可以表示為 CPU 運算時間 $T_{compute}$ 與磁碟 I/O 所需時間 $T_{io}$ 的總和。

$$ T_{total} = T_{compute} + T_{io} $$

在 WSL1 的情況下，由於會產生將 Linux 側的操作轉換為 NTFS 操作的負擔，因此 I/O 時間可以用以下模型表示。其中，$n$ 為檔案操作的次數，$t_{ntfs\_syscall}$ 為 Windows 側系統呼叫的執行時間，$t_{trans}$ 為轉換層的負擔。

$$ T_{wsl1\_io} = \sum_{i=1}^{n} (t_{ntfs\_syscall_i} + t_{trans_i}) $$

另一方面，在 WSL2 的情況下，因為核心會直接對 ext4 檔案系統發出 I/O，負擔僅有虛擬化造成的極微小延遲 $t_{virt}$。

$$ T_{wsl2\_io} = \sum_{i=1}^{n} (t_{ext4_i} + t_{virt_i}) $$

在一般的檔案系統中，因為 $t_{ext4} \ll t_{ntfs\_syscall} + t_{trans}$，當 $n$ 非常大（執行數萬到數十萬次的檔案操作）時，WSL1 與 WSL2 的 I/O 時間差距會呈指數級別拉開。

此外，若將虛擬化環境中 CPU 運算負擔的比例設為 $\rho$，在最新的硬體輔助虛擬化（Intel VT-x / AMD-V）下，$\rho \approx 0.01 \sim 0.03$（大約 1% 到 3%）。因此，即使在純粹的運算任務中，也能發揮出毫不遜色於原生 Linux 環境的 $97\% \sim 99\%$ 效能。

3. 安裝與基底建構

在 Windows 10/11 中，WSL2 的安裝變得非常簡單。只要以系統管理員權限開啟 PowerShell，並執行以下指令即可。

1
2
3
4
5
6


# 預設將安裝 WSL2 與 Ubuntu
wsl --install

# 若要指定特定的發行版
# 可透過 wsl --list --online 進行確認
wsl --install -d Ubuntu-24.04

安裝後經過重新啟動，首次啟動時會要求設定 UNIX 的使用者名稱與密碼。這個使用者與 Windows 的使用者是獨立的，僅在 WSL 內部有效。

如果您已經在使用 WSL1，請使用以下指令轉換為 WSL2。

1
2
3
4
5


# 將現有的發行版轉換為 WSL2
wsl --set-version Ubuntu 2

# 將未來新增的發行版預設為 WSL2
wsl --set-default-version 2

4. 資源控制的秘訣：.wslconfig 與 wsl.conf

WSL2 最大的陷阱之一就是「無限制地消耗記憶體（Vmmem 處理程序過度膨脹）」。由於 WSL2 會使用 Linux 核心的分頁快取（Page Cache），每次進行 I/O 操作都會無止盡地耗盡主機（Windows）的記憶體。為了防止這種情況，必須透過設定檔來限制資源。

WSL2 的設定檔分為兩個：會影響整個 Windows 的 .wslconfig，以及會影響各個發行版內部的 wsl.conf。

4.1. .wslconfig (Windows 側)

在 Windows 的使用者設定檔目錄（C:\Users\<使用者名稱>\.wslconfig）建立檔案，並控制配置給 VM 的資源。

 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


# C:\Users\<使用者名稱>\.wslconfig
[wsl2]
# 分配給 VM 的最大記憶體量。建議為主機總記憶體的 50% 到 75% 左右
memory=16GB

# 使用的 CPU 核心數（省略時將使用全部核心）
processors=8

# 交換檔案（Swap file）的大小
swap=8GB

# 交換檔案的儲存位置（如果想節省 C 磁碟機空間的話）
# swapfile=D:\\wsl\\swap.vhdx

# 啟用 localhost 轉發（為了從 Windows 側透過 localhost 存取 WSL）
localhostForwarding=true

# 自動釋放記憶體（僅限 Windows 11）
# 動態釋放分頁快取，防止 Vmmem 過度膨脹
autoMemoryReclaim=dropcache

[experimental]
# Windows 11 22H2 之後可用的進階網路功能
# 藉此可以支援 IPv6，以及讓 WSL 與 Windows 之間共用同一個 IP 位址
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true

4.2. wsl.conf (Linux 側)

編輯 WSL 內的 /etc/wsl.conf，以控制發行版專屬的行為。

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


# /etc/wsl.conf (在 WSL 內部編輯)
[network]
# 停用 WSL 啟動時自動產生的 /etc/resolv.conf
# 如果想設定自訂的 DNS（例如：8.8.8.8）時會很有用
generateResolvConf=false

# 設定自訂的主機名稱
hostname=WSL-DevNode

[automount]
# 掛載 Windows 磁碟機時的設定
enabled=true
options="metadata,uid=1000,gid=1000,umask=022"
# 將 C 磁碟機的掛載點從 /mnt/c 變更為 /c（縮短路徑）
root=/

[boot]
# 啟用 systemd（WSL 0.67.6 之後）
# 藉此，snap 與各種守護行程（如 Docker 等）就能原生執行
systemd=true

[user]
# 預設登入的使用者
default=kenji

為了讓這些設定生效，必須在 PowerShell 執行 wsl --shutdown，完全停止 WSLVM 後再重新啟動。

5. 終極的終端機環境：Zsh + Powerlevel10k

如果繼續使用預設的 bash，生產力將無法提升。結合擁有強大自動補齊功能與高可視性的 Zsh，以及超快速的主題「Powerlevel10k」，來建構最強的命令提示字元（Prompt）。

5.1. 安裝與設定 Windows Terminal

從 Microsoft Store 安裝「Windows Terminal」。開啟 JSON 設定檔（settings.json），將預設設定檔設定為 WSL（Ubuntu），並將字型變更為適合開發的 Nerd Font（例如：HackGen Console NF 或 MesloLGS NF）。

5.2. 安裝 Zsh 與 Oh My Zsh

在 WSL 的終端機執行以下指令。

1
2
3
4
5
6


# 更新套件並安裝 Zsh
sudo apt update && sudo apt upgrade -y
sudo apt install -y zsh git curl

# 執行 Oh My Zsh 安裝指令碼
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

5.3. 匯入 Powerlevel10k 與外掛程式

匯入能進一步強化 Zsh 的外掛程式（語法凸顯與輸入補齊），以及 Powerlevel10k 主題。

1
2
3
4
5
6
7
8


# Powerlevel10k
git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

# zsh-autosuggestions
git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

# zsh-syntax-highlighting
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

編輯 ~/.zshrc，啟用主題與外掛程式。

1
2
3
4
5


# ~/.zshrc 的變更點
ZSH_THEME="powerlevel10k/powerlevel10k"

# 新增至外掛程式的陣列中
plugins=(git zsh-autosuggestions zsh-syntax-highlighting)

存檔並執行 source ~/.zshrc 後，就會啟動 Powerlevel10k 的設定精靈（p10k configure）。請依照畫面指示，自訂您喜歡的提示字元（提示字元樣式、是否顯示圖示、要顯示的資訊等）。Git 的分支名稱與狀態、Node.js 的版本、指令的執行時間等將會即時顯示，開發效率將會有飛躍性的提升。

6. VS Code Remote - WSL 的無縫整合

在 WSL2 的開發中，能從安裝在 Windows 側的 IDE（Visual Studio Code）無縫存取 WSL 內檔案的機制就是「Remote - WSL」擴充功能。

架構解說

以下的循序圖展示了 VS Code 是如何與 WSL2 進行通訊的。

sequenceDiagram
autonumber
participant U as "開發者"
participant V as "VS Code UI (Windows)"
participant S as "VS Code 伺服器 (WSL2)"
participant F as "ext4 檔案系統 (WSL2)"
U->>V: "在 WSL 終端機輸入 `code .`"
V->>S: "透過 Vsock 建立 RPC 連線"
Note over V,S: 不使用 TCP/IP，而是使用 Hyper-V Socket 進行通訊
S->>F: "讀取原始碼檔案 / 執行 Linter"
F-->>S: "回傳資料與分析結果"
S-->>V: "將 Language Server 的結果串流至 UI"
V-->>U: "顯示語法凸顯與錯誤"

Windows 側的 VS Code 僅作為一個單純的「精簡型用戶端（UI）」運作，而 Language Server、除錯器（Debugger）、終端機執行等繁重的處理，全都在 WSL 側的「VS Code 伺服器」上進行。這樣一來，不需在 Windows 側安裝 Node.js 或 Python，就能只在 WSL 側保持環境的乾淨。

必備的 VS Code 設定

從 VS Code 的「擴充功能」中安裝 “WSL” (ms-vscode-remote.remote-wsl)。之後，只要在 WSL 的終端機切換至專案目錄，並執行 code .，就能在開啟該目錄的狀態下啟動 Windows 側的 VS Code。

重要的注意事項（換行字元問題）： Windows 與 Linux 的換行字元不同（Windows 是 CRLF，Linux 是 LF）。在 WSL 上進行開發時，請務必將 Git 的 core.autocrlf 設定，以及 VS Code 的檔案預設設定統一為 LF。如果忽略這一點，在執行 Shell Script 或 Docker 容器時將會遇到莫名其妙的錯誤。

1
2


# 在 WSL 側設定 Git 的換行字元
git config --global core.autocrlf input

也在 VS Code 的 settings.json（遠端設定）中新增以下內容。

1
2
3
4


{
 "files.eol": "\n",
 "terminal.integrated.defaultProfile.linux": "zsh"
}

7. Docker Desktop 與 WSL2 Integration 的最佳化

在 WSL2 環境中使用 Docker，主要有兩種方法。

安裝 Docker Desktop for Windows，並啟用 WSL2 整合功能
在 WSL2 內部（如 Ubuntu 等）直接安裝原生的 Docker Engine

方法 1：Docker Desktop（推薦）

由於可以透過 GUI 進行管理，且在 Windows/WSL 之間可以輕鬆透明地存取容器，因此大多情況下推薦使用此方法。從 Docker Desktop 的設定（Settings）中確認以下事項。

勾選 General -> Use the WSL 2 based engine。
勾選 Resources -> WSL Integration -> Enable integration with my default WSL distro，並將要使用的發行版（Ubuntu）的開關切換為開啟。

如此一來，就能從 WSL2 的終端機直接執行 docker 指令，並透過由 Docker Desktop 管理的專屬輕量級 VM（docker-desktop 與 docker-desktop-data）來與 Docker 守護行程進行通訊。

方法 2：直接匯入原生 Docker Engine

如果是受到企業網路的限制（為了避免 Docker Desktop 的收費等），或是想要將效能負擔降到極限，可以在 /etc/wsl.conf 中啟用 systemd 後，將其當作純粹的 Ubuntu 伺服器來安裝 Docker。

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


# 啟用 systemd 的 WSL2 Ubuntu 上的 Docker 官方安裝步驟摘錄
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# 新增版本庫
echo \
 "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
 "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
 sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 將目前的使用者加入 docker 群組（為了不需 sudo 即可執行）
sudo usermod -aG docker $USER

重新啟動後，systemctl start docker 就能和原生 Linux 環境完全一樣地運作，並發揮高效能。

8. SSH 金鑰的整合：Windows 與 WSL 的無縫驗證

在進行 Git 的 SSH 複製或 SSH 連線至遠端伺服器時，在 Windows 側和 WSL 側分別管理不同的 SSH 金鑰是一件非常麻煩的事。為了兼顧安全性與便利性，可以設定將 Windows 側執行的 SSH 代理（或是 1Password 等密碼管理工具）橋接至 WSL 側。

這裡將解說作為最安全且現代的方法：利用 1Password 的 SSH 代理功能或 Windows 的 OpenSSH Authentication Agent，並使用 npiperelay 或 socat 將其轉發至 WSL2 的 UNIX 網域通訊端（Domain Socket）的方法。

ssh-agent 的通訊端轉發

通常以 Windows 具名管道（Named Pipe）提供的 SSH 代理，必須轉換為 WSL 側的通訊端檔案。利用 wsl-ssh-agent 或是 1Password 提供的功能就可以輕鬆達成。

從 1Password 的設定畫面中啟用「開發者」->「使用 SSH 代理」。接著，在 WSL 側的 ~/.zshrc 或 ~/.bashrc 中加入以下設定，使其在登入時自動綁定通訊端。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 寫入 ~/.zshrc 的內容（使用 1Password SSH Agent 的範例）
export SSH_AUTH_SOCK=$HOME/.ssh/agent.sock
# 當 WSL 啟動時通訊端不存在，或處理程序未綁定時，使用 socat 與 npiperelay 進行轉發
ALREADY_RUNNING=$(ps -aux | grep "[n]piperelay.exe -ei -s //./pipe/openssh-ssh-agent" | wc -l)
if [ $ALREADY_RUNNING -eq 0 ]; then
 if [ -S $SSH_AUTH_SOCK ]; then
 rm $SSH_AUTH_SOCK
 fi
 # 在背景啟動 socat，並將 Windows 側的 Named Pipe 連接至 WSL 側的 UNIX 通訊端
 (setsid socat UNIX-LISTEN:$SSH_AUTH_SOCK,fork EXEC:"npiperelay.exe -ei -s //./pipe/openssh-ssh-agent",nofork &) >/dev/null 2>&1
fi

※需要事先在 Windows 側安裝 npiperelay.exe 並設定好環境變數路徑。

設定完成後，從 WSL 的終端機執行 ssh-add -l 時，就會顯示在 1Password 或是 Windows 側所註冊的 SSH 金鑰公鑰清單。這樣一來，不需將私鑰檔案複製到 WSL 內，也能安全地通過驗證。

9. 維護：膨脹的 VHDX 最佳化（壓縮）

WSL2 最大的缺點之一是「即使刪除 Docker 映像檔或檔案，Windows 側虛擬磁碟（.vhdx）的檔案大小也不會自動縮小」的規格。長期開發下來，ext4.vhdx 檔案可能會膨脹到數十 GB 到數百 GB。

為了釋放磁碟空間，必須定期從 Windows 側將 VHDX 最佳化（Compact）。

首先，完全關閉 WSL。
1

wsl --shutdown
開啟擁有系統管理員權限的 PowerShell，並執行以下的 diskpart 指令，或是 Hyper-V 模組的 Optimize-VHD 指令（僅限啟用 Hyper-V 時才能使用後者）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 能夠使用 Hyper-V 模組的情況
Optimize-VHD -Path "$env:LOCALAPPDATA\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState\ext4.vhdx" -Mode Full

# 使用 diskpart 的情況
diskpart
# 在以下的提示字元中以互動方式輸入
DISKPART> select vdisk file="C:\Users\<使用者名稱>\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState\ext4.vhdx"
DISKPART> attach vdisk readonly
DISKPART> compact vdisk
DISKPART> detach vdisk
DISKPART> exit

定期執行此操作，就能找回被白白消耗的 C 磁碟機空間。

10. 結語

WSL2 已經完全超越了單純只是「在 Windows 上運作的附屬 Linux」的框架，進化成了不亞於 MacOS 或原生 Linux 機器，甚至更強大的開發平台。

藉由套用本次解說的所有設定（透過 .wslconfig 的資源最佳化、透過 Zsh + Powerlevel10k 的終端機強化、透過 VS Code Remote 的透明存取，以及 SSH 整合與 VHDX 的維護），就能完成一個無壓力、高速且安全的「終極開發環境」。

雖然建構環境需要花費一點功夫，但只要設定過一次，未來的工程開發的生產力絕對會有飛躍性的提升。請務必配合自身的專案與喜好，以此指南為基礎，探索更進階的自訂設定。