在 WSL 用 wslc 跑 Linux 容器
這篇教你在 Windows 的 WSL 2.9.3+ 上用 wslc.exe 建置、執行與檢查 Linux 容器。
這篇教你在 Windows 的 WSL 2.9.3+ 上用 wslc.exe 建置、執行與檢查 Linux 容器。
這篇給 Windows 開發者看，目標是在 WSL 內建立一套本機容器流程，不必另外安裝獨立的容器引擎。照做完，你會拿到可用的 WSL、已驗證的 wslc、可執行的範例容器，以及自己專案的建置路徑。
你也會學會如何轉發埠、查看日誌、清理停止中的容器，讓整套流程維持輕量且好維護。這個做法也適合搭配 Visual Studio Code 與 Ubuntu 這類 Linux 發行版。
開始之前
訂閱 AI 趨勢週報
每週精選模型發布、工具應用與深度分析，直送信箱。不定期，不騷擾。
不會寄垃圾信，隨時可取消。
- Windows 11 或已安裝 WSL 的 Windows 10
- WSL 版本 2.9.3 以上
- Windows 上可開啟 PowerShell
- WSL 發行版已安裝，例如 Ubuntu
- Git 已安裝在 WSL 發行版內
- 選用：Visual Studio Code 與 WSL 擴充功能
- 選用：Windows Terminal
Step 1: 更新 WSL 預覽版
先把 WSL 更新到包含 wslc.exe 的版本，這是後面所有容器指令的基礎。沒有達到版本門檻，後續步驟就無法順利執行。
wsl --update --pre-release
wsl --version你應該看到 WSL 版本顯示為 2.9.3 以上。若更新成功，就代表基礎 runtime 已準備好。
Step 2: 驗證 wslc 指令
接著確認容器 CLI 已隨 WSL 可用，先驗證工具存在，再開始跑映像檔。這一步可以避免把問題誤判成映像檔或網路錯誤。
wslc version
wslc --help你應該看到 wslc 的版本字串，以及包含 run、build、image、container、stats 的說明頁。這表示 PowerShell 已能呼叫這個 CLI。
Step 3: 執行 hello-world 容器
先用最小映像檔做端到端測試，確認拉取、啟動與輸出都正常。這是最快的通路驗收，也能提早排除 runtime 問題。
wslc run --rm hello-world你應該看到 Hello 訊息，表示安裝流程看起來已經可正常運作。若有這段輸出，就代表 WSL 容器路徑已通過基本驗收。
Step 4: 啟動 nginx 並轉發埠
完成煙霧測試後，改跑一個背景服務並映射到 Windows 本機埠。這會讓你能直接用瀏覽器或本機工具測試服務。
wslc run -d --rm -p 8080:80 --name web nginx
curl localhost:8080
wslc container list
wslc exec web cat /etc/os-release
wslc container stop web你應該看到 localhost:8080 回應內容、容器清單中出現正在執行的項目，以及容器內的 Linux 版本資訊。停止容器後，因為使用了 --rm，所以容器會自動移除。
Step 5: 建置自己的 Containerfile
現在把範例映像檔換成你自己的應用映像檔。這一步的具名產出是專案根目錄中的 Containerfile，以及一個可重複使用的標籤映像檔。
FROM python:3
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]在包含 Containerfile 的資料夾中執行建置，並替映像檔取一個可重用的 tag。Microsoft 建議把專案檔案放在 WSL 檔案系統內，Linux 工具讀寫會更快。
wslc build -t helloworld-django .
wslc image list你應該在映像檔清單中看到新建好的 image。若從 WSL 檔案系統建置，檔案存取通常會比放在 Windows 檔案系統更順。
Step 6: 啟動、檢查與清理應用容器
最後把自製映像檔跑起來，查看日誌，再把資源清乾淨。這會形成可重複的開發與除錯流程。
wslc run -d --rm -p 8000:8000 --name django helloworld-django
wslc container list
wslc container logs django
wslc exec django uname
wslc container stop django
wslc container prune
wslc image prune你應該看到應用可在 http://localhost:8000/ 開啟、容器日誌可讀，且 uname 回報 Linux。清理完成後，停止中的容器與未使用映像檔都會被移除。
| 指標 | 基準／優化前 | 結果／優化後 |
|---|---|---|
| WSL 版本 | 低於 2.9.3 | 2.9.3 以上且已套用預覽更新 |
| 容器 CLI | 無法使用 wslc.exe | wslc version 回傳有效版本 |
| 煙霧測試 | 尚未驗證容器 | hello-world 輸出 Hello 確認訊息 |
| 埠轉發 | 無法對外提供本機服務 | localhost:8080 或 localhost:8000 可連到容器 |
常見錯誤
- WSL 版本低於 2.9.3。修法：執行
wsl --update --pre-release，再用wsl --version確認。 - 專案放在 Windows 檔案系統。修法：把程式碼移到 WSL 檔案系統，Linux 工具讀寫會更快。
- 忘記轉發容器埠。修法：在測試前加上
-p host:container，例如-p 8000:8000。
接下來可以看什麼
下一步可以看 WSL 容器總覽、容器 API 範例，以及 VS Code 的 WSL 工作流程，進一步把這套環境接到除錯、自動化與自己的服務上。