在 Windows 上跑 Linux 容器這件事我前前后后換過(guò)四套方案。最早是裝個(gè)完整虛擬機(jī)開機(jī)三分鐘內(nèi)存先吃掉一半后來(lái)用桌面版容器工具圖形界面點(diǎn)著舒服但一旦要和命令行腳本、流水線對(duì)齊就總隔著一層說(shuō)不清的封裝再后來(lái)是在 WSL 里手動(dòng)裝容器引擎能跑但每次換機(jī)器都要重來(lái)一遍那套拳法。wslcWSL Containers出現(xiàn)之后這套流程被壓縮成了一個(gè)命令的事——容器直接跑在 WSL 內(nèi)核之上不需要額外開虛擬機(jī)也不需要一套獨(dú)立的后臺(tái)服務(wù)常駐。這篇是我把 wslc 從零裝到日常使用、再踩了幾個(gè)坑之后的完整復(fù)盤包含安裝順序、命令鏈路、鏡像構(gòu)建、路徑映射陷阱和排障思路。適合兩類人看一是在 Windows 上做 Linux 側(cè)開發(fā)、被環(huán)境折騰過(guò)的二是已經(jīng)裝上了 wslc但卡在掛載、端口或者構(gòu)建失敗上出不來(lái)的。命令細(xì)節(jié)我會(huì)給出具體寫法同時(shí)提醒哪些地方會(huì)隨預(yù)覽版本變化——這一點(diǎn)很重要?jiǎng)e把某一版的命令當(dāng)成永久契約。1. wslc 的定位它和虛擬機(jī)方案、桌面容器工具的分界線在哪1.1 三層隔離模型進(jìn)程級(jí)、發(fā)行版級(jí)、容器級(jí)要理解 wslc 為什么輕得先把隔離這件事拆成三層看。最外面一層是虛擬機(jī)它模擬整套硬件有自己的內(nèi)核隔離最徹底代價(jià)是啟動(dòng)慢、內(nèi)存占用固定且偏高中間一層是 WSL 里的 Linux 發(fā)行版實(shí)例它共享宿主內(nèi)核的部分能力但有自己的文件系統(tǒng)、用戶體系和軟件包管理本質(zhì)是一個(gè)輕量虛擬機(jī)加系統(tǒng)調(diào)用翻譯最里面一層就是容器它只做命名空間和資源限制進(jìn)程直接跑在同一個(gè)內(nèi)核上沒(méi)有獨(dú)立的引導(dǎo)過(guò)程。wslc 的位置很有意思它把容器這一層直接架在了 WSL 的發(fā)行版實(shí)例里面。也就是說(shuō)你不需要先開一個(gè)虛擬機(jī)再在虛擬機(jī)里裝容器引擎再在引擎里跑容器——這三層被壓成了兩層。實(shí)際感受是wslc run一個(gè)基礎(chǔ)鏡像從敲下回車到出現(xiàn) shell 提示符通常在兩秒以內(nèi)而同樣的事情在完整虛擬機(jī)方案里要二十秒起步。這個(gè)壓縮帶來(lái)的直接好處是資源賬好算了。你不需要為虛擬機(jī)本身預(yù)留一份固定內(nèi)存容器不用的時(shí)候它就是個(gè)靜止的進(jìn)程集合不占 CPU。但代價(jià)也要說(shuō)清楚既然容器共享的是 WSL 實(shí)例的內(nèi)核那么內(nèi)核參數(shù)、內(nèi)核模塊、某些需要特權(quán)的操作就會(huì)受限于這個(gè)實(shí)例的配置而不是像獨(dú)立虛擬機(jī)那樣隨便折騰。我在做網(wǎng)絡(luò)抓包相關(guān)實(shí)驗(yàn)的時(shí)候就撞到過(guò)這個(gè)邊界后來(lái)只能在實(shí)例層面調(diào)整容器內(nèi)部改不動(dòng)。理解這三層之后很多為什么這個(gè)功能在別處能用、在這里不行的疑問(wèn)就有答案了不是工具壞了是它站在了不同的隔離層級(jí)上。1.2 與桌面版容器工具的實(shí)際差異對(duì)照很多人第一反應(yīng)是我桌面上的容器工具不是挺好用嗎為什么要換。這個(gè)問(wèn)題問(wèn)得對(duì)我一開始也這么想。差異不在功能多少而在鏈路上多了什么、少了什么。我把自己實(shí)際用下來(lái)的對(duì)比整理成了一張表都是日常會(huì)碰到的場(chǎng)景對(duì)比維度桌面版容器工具wslc后臺(tái)常駐服務(wù)需要獨(dú)立服務(wù)進(jìn)程開機(jī)自啟依附 WSL 實(shí)例無(wú)常駐守護(hù)進(jìn)程首次啟動(dòng)耗時(shí)數(shù)十秒冷啟動(dòng)更久通常 1~3 秒與 Linux 側(cè)文件系統(tǒng)交互跨文件系統(tǒng)邊界大量小文件讀寫明顯變慢容器與實(shí)例同一文件系統(tǒng)接近原生命令行一致性命令可用但部分行為經(jīng)過(guò)封裝轉(zhuǎn)換命令語(yǔ)義貼近 Linux 原生圖形化管理有完整界面以命令行和配置文件為主資源占用固定預(yù)留內(nèi)存不易按需回收按需分配空閑時(shí)占用低與腳本、流水線對(duì)齊需要額外適配層腳本可直接復(fù)用這張表里最值得說(shuō)的是第三行和第五行?？缥募到y(tǒng)這件事表面上看只是慢一點(diǎn)實(shí)際影響的是整個(gè)開發(fā)循環(huán)的體感。我曾經(jīng)在一個(gè)包含幾萬(wàn)個(gè)依賴文件的前端項(xiàng)目上做過(guò)對(duì)比同樣的安裝依賴步驟跨邊界方案要六分多鐘同文件系統(tǒng)內(nèi)不到一分半。這種差距不是優(yōu)化能補(bǔ)的是架構(gòu)決定的。反過(guò)來(lái)說(shuō)圖形界面這一項(xiàng)確實(shí)是短板。如果你的工作流高度依賴點(diǎn)選、看面板、拖拽管理鏡像那 wslc 會(huì)讓你不適應(yīng)。但對(duì)大多數(shù)把命令寫進(jìn)腳本、把步驟寫進(jìn)文檔的人來(lái)說(shuō)命令行反而是優(yōu)勢(shì)——可復(fù)制、可版本化、可審查。1.3 適合遷移與不適合遷移的項(xiàng)目類型不是所有項(xiàng)目都值得遷。我的判斷標(biāo)準(zhǔn)很簡(jiǎn)單看這個(gè)項(xiàng)目里容器是主角還是配角。如果容器是主角——比如你在做微服務(wù)拆分、需要本地起三四個(gè)服務(wù)互相調(diào)用、需要精確控制運(yùn)行時(shí)依賴版本——那 wslc 很合適。它啟動(dòng)快意味著你可以頻繁銷毀重建把環(huán)境不一致這個(gè)老問(wèn)題從根上掐掉。我現(xiàn)在做聯(lián)調(diào)習(xí)慣是每次拉最新代碼后直接把舊容器刪掉重起成本幾乎為零這在小規(guī)模項(xiàng)目里是很奢侈的體驗(yàn)。如果容器是配角——比如你只是偶爾需要一個(gè)特定版本的解釋器跑一下腳本——那我建議你直接用 WSL 發(fā)行版實(shí)例里裝的解釋器別上容器。多一層封裝就多一層解釋成本出了問(wèn)題還要判斷是容器的問(wèn)題還是實(shí)例的問(wèn)題。還有一類要格外謹(jǐn)慎需要內(nèi)核級(jí)特性的場(chǎng)景比如自定義網(wǎng)絡(luò)棧、需要加載特定內(nèi)核模塊、需要完整 systemd 行為的。這些在共享內(nèi)核模型下都有邊界不是不能做是要額外折騰投入產(chǎn)出比不劃算。我一般遇到這類需求就直接退回虛擬機(jī)別硬扛。2. 裝之前先把環(huán)境賬算清楚功能啟用順序與版本核對(duì)2.1 硬件與系統(tǒng)版本的門檻確認(rèn)安裝失敗最常見的原因不是命令敲錯(cuò)了是前置條件沒(méi)滿足。動(dòng)手之前有兩件事必須先確認(rèn)。第一件是硬件虛擬化。這一項(xiàng)在任務(wù)管理器的性能頁(yè)里能看到標(biāo)著虛擬化已啟用就對(duì)了。如果顯示已禁用得進(jìn)固件設(shè)置里打開。這一步我吃過(guò)虧——有臺(tái)機(jī)器裝完一切正常唯獨(dú)容器啟動(dòng)后立刻退出日志還是空的排查了兩個(gè)小時(shí)才發(fā)現(xiàn)是虛擬化沒(méi)開。因?yàn)椴糠止δ茉谔摂M化關(guān)閉時(shí)仍然能裝、能跑命令只是容器一啟動(dòng)就死報(bào)錯(cuò)還特別隱晦。第二件是系統(tǒng)版本。WSL 的容器能力是跟著 WSL 版本走的不是跟著系統(tǒng)大版本走的。你得先確認(rèn)當(dāng)前的 WSL 版本足夠新用這條命令看wsl --version輸出里會(huì)列出 WSL 版本、內(nèi)核版本、以及 WSLg 之類的組件版本。如果這條命令直接報(bào)無(wú)法識(shí)別說(shuō)明你的環(huán)境還停留在靠系統(tǒng)組件提供 WSL 的舊形態(tài)需要先升級(jí)到基于應(yīng)用包分發(fā)的新形態(tài)再談容器能力。這個(gè)升級(jí)動(dòng)作本身很輕通常一條命令加一次重啟但順序不能反——先升 WSL再裝 wslc。我建議把版本號(hào)記下來(lái)寫在項(xiàng)目文檔的環(huán)境要求里。原因是 wslc 目前還在快速迭代不同版本之間命令名、參數(shù)名、默認(rèn)行為都可能變。我在兩個(gè)不同版本的機(jī)器上執(zhí)行同一條命令輸出格式就不一樣。把版本釘住出問(wèn)題時(shí)才有對(duì)照基準(zhǔn)。2.2 可選功能啟用的先后順序與重啟節(jié)奏Windows 的可選功能有依賴關(guān)系順序錯(cuò)了會(huì)出現(xiàn)啟用成功但實(shí)際不生效的假象。我總結(jié)的順序是先啟用虛擬機(jī)平臺(tái)相關(guān)功能再啟用子系統(tǒng)相關(guān)功能最后確認(rèn)默認(rèn)版本指向。具體操作用管理員權(quán)限打開終端# 第一步啟用虛擬機(jī)平臺(tái)能力這是容器運(yùn)行的基礎(chǔ) dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart # 第二步啟用 Linux 子系統(tǒng)能力 dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart # 第三步統(tǒng)一重啟不要中途重啟 shutdown /r /t 0我特意把兩步寫在一起、最后統(tǒng)一重啟是因?yàn)榉謨纱沃貑⒑芾速M(fèi)時(shí)間而且第二步在某些系統(tǒng)上會(huì)提示需要重啟才能繼續(xù)容易讓人誤以為第一步失敗了。重啟之后把默認(rèn)版本設(shè)為 2wsl --set-default-version 2這一步的意義在于容器能力依賴的是 WSL 2 的輕量虛擬化架構(gòu)版本 1 是不行的。如果你之前裝過(guò)舊版發(fā)行版它們可能還停留在版本 1需要單獨(dú)轉(zhuǎn)換wsl --list --verbose wsl --set-version 發(fā)行版名稱 2轉(zhuǎn)換過(guò)程會(huì)重建文件系統(tǒng)耗時(shí)取決于里面有多少文件。我有次在一個(gè)塞了幾十 G 依賴的實(shí)例上做轉(zhuǎn)換等了將近十分鐘中途一度以為卡死了。實(shí)際上它在正常干活別中斷。2.3 安裝本體與首次初始化前置條件齊了安裝本體本身反而最簡(jiǎn)單。按應(yīng)用包分發(fā)的形態(tài)可以直接用包管理工具裝winget install --id Microsoft.WSL -e裝完再用wsl --version確認(rèn)一遍版本號(hào)應(yīng)該比之前新。如果你所在的環(huán)境不方便聯(lián)網(wǎng)也可以下載離線包手動(dòng)安裝思路一樣注意包的架構(gòu)要和系統(tǒng)匹配多數(shù)機(jī)器是 x64部分輕薄本可能是 ARM 架構(gòu)裝錯(cuò)了會(huì)提示不兼容。wslc 的命令行入口通常在 WSL 升級(jí)后一并提供可以在 WSL 實(shí)例里直接調(diào)用wslc --help如果這條命令提示找不到有兩種可能一是 WSL 版本還不夠新二是不在 WSL 實(shí)例里執(zhí)行。注意wslc 的命令要在 WSL 實(shí)例內(nèi)部執(zhí)行而不是在 Windows 側(cè)的 PowerShell 里執(zhí)行。這一點(diǎn)和很多人習(xí)慣的在 PowerShell 里敲 wsl 加參數(shù)不同容易混淆。我自己的習(xí)慣是先wsl進(jìn)實(shí)例再在實(shí)例里操作路徑清晰。首次運(yùn)行會(huì)做一次初始化檢查運(yùn)行環(huán)境、準(zhǔn)備存儲(chǔ)目錄、注冊(cè)默認(rèn)網(wǎng)絡(luò)配置。這個(gè)過(guò)程通常幾秒鐘屏幕上會(huì)打印一些檢查項(xiàng)。我建議把這段輸出完整看一遍它列出的每一項(xiàng)都是后面排障的線索。有一次我跳過(guò)沒(méi)看后面遇到網(wǎng)絡(luò)不通回頭才發(fā)現(xiàn)初始化時(shí)就已經(jīng)提示某組件未就緒。2.4 三步驗(yàn)證法判斷裝上了和能用了裝完不等于能用。我用一套三步驗(yàn)證法逐層排除問(wèn)題第一步驗(yàn)證命令行入口。執(zhí)行wslc version或wslc --version能打印出版本信息說(shuō)明二進(jìn)制在、路徑對(duì)。第二步驗(yàn)證運(yùn)行能力。拉一個(gè)最小的基礎(chǔ)鏡像并跑一條命令wslc pull alpine:latest wslc run --rm alpine:latest echo container ok看到輸出container ok就說(shuō)明鏡像拉取、容器創(chuàng)建、進(jìn)程執(zhí)行這條鏈路通了。這一步失敗問(wèn)題通常出在鏡像拉取或者存儲(chǔ)權(quán)限上。第三步驗(yàn)證網(wǎng)絡(luò)與文件系統(tǒng)。跑一個(gè)帶端口映射的服務(wù)同時(shí)掛一個(gè)目錄進(jìn)去wslc run --rm -d --name probe -p 8080:80 -v /tmp/probe:/usr/share/nginx/html nginx:alpine curl -s http://localhost:8080如果 curl 能拿到頁(yè)面內(nèi)容說(shuō)明端口映射和掛載都正常。三步都過(guò)環(huán)境就算真正可用了。這套驗(yàn)證我建議存成一個(gè)腳本換機(jī)器、升級(jí)版本之后都跑一遍比憑感覺判斷靠譜得多。3. 第一個(gè)容器跑通從拉鏡像到端口映射的完整鏈路3.1 鏡像從哪來(lái)、存在哪鏡像的來(lái)源和存放位置這兩件事看起來(lái)是細(xì)節(jié)實(shí)際決定了很多為什么磁盤好像不夠用了的困惑。來(lái)源默認(rèn)是公共鏡像倉(cāng)庫(kù)。wslc pull會(huì)按名稱去拉取格式是倉(cāng)庫(kù)地址/命名空間/鏡像名:標(biāo)簽。標(biāo)簽不寫默認(rèn)取latest而latest這個(gè)東西在生產(chǎn)里是災(zāi)難——你今天拉的latest和上周拉的latest可能完全是兩份不同的東西。我的做法是始終顯式寫版本標(biāo)簽?zāi)呐聦憘€(gè)alpine:3.20這種也比latest強(qiáng)。存放位置上鏡像和解壓后的層都落在 WSL 實(shí)例的虛擬磁盤文件里不是散落在 Windows 的某個(gè)目錄。這個(gè)設(shè)計(jì)帶來(lái)兩個(gè)后果一是你在 Windows 資源管理器里看不到鏡像文件別去那兒找二是磁盤占用會(huì)整體體現(xiàn)在那個(gè)虛擬磁盤文件的大小上而虛擬磁盤文件有個(gè)特點(diǎn)——只增不減。刪掉鏡像占用空間不一定立刻還給系統(tǒng)需要額外做一次壓縮。查看當(dāng)前有哪些鏡像、占了多少wslc images wslc system dfimages列的是鏡像清單system df給的是匯總賬包括鏡像、容器、構(gòu)建緩存各占多少。我第一次跑df的時(shí)候被構(gòu)建緩存那一欄驚到了——緩存比鏡像本身還大。后面專門講清理。3.2 運(yùn)行、進(jìn)入、退出的正確姿勢(shì)跑容器有兩種典型用法一種是執(zhí)行一次性命令一種是進(jìn)交互式 shell。前者用wslc run --rm alpine:latest ls /etc--rm的意思是容器退出后自動(dòng)刪除不留垃圾。這個(gè)參數(shù)在跑一次性命令時(shí)幾乎必加否則你會(huì)發(fā)現(xiàn)wslc ps -a里堆了幾十個(gè)已退出的容器。后者是進(jìn) shellwslc run --rm -it alpine:latest /bin/sh-i保持標(biāo)準(zhǔn)輸入打開-t分配一個(gè)偽終端。這兩個(gè)參數(shù)少一個(gè)都會(huì)出問(wèn)題只加-i你在 shell 里看不到提示符輸入也沒(méi)回顯只加-t某些交互程序會(huì)立刻退出。我一開始圖省事只加了-it里的一個(gè)折騰半天以為是鏡像壞了。進(jìn)出容器還有一條更省事的路徑就是對(duì)已經(jīng)跑起來(lái)的容器執(zhí)行命令不必新開wslc exec -it 容器名 /bin/sh退出交互式 shell 用exit或者 CtrlD。這里有個(gè)容易忽略的點(diǎn)如果你是用wslc run -it起的容器并且沒(méi)加--rm退出后容器處于停止?fàn)顟B(tài)想再進(jìn)去要wslc start再exec。而加了--rm的容器退出即消失數(shù)據(jù)也不留。取舍看你是在調(diào)試還是在跑服務(wù)。3.3 端口映射與宿主機(jī)訪問(wèn)路徑端口映射的寫法是-p 宿主端口:容器端口。這里有個(gè)認(rèn)知需要糾正映射之后你在 Windows 側(cè)的瀏覽器里訪問(wèn)localhost:宿主端口是能通的不需要知道 WSL 實(shí)例的 IP。這是 WSL 網(wǎng)絡(luò)特性帶來(lái)的便利很多人不知道還在費(fèi)勁查實(shí)例 IP。但如果你的服務(wù)又需要被局域網(wǎng)里其他機(jī)器訪問(wèn)情況就復(fù)雜了。默認(rèn)情況下映射出來(lái)的端口只在本機(jī)回環(huán)地址上監(jiān)聽局域網(wǎng)訪問(wèn)不到。這需要在實(shí)例層面調(diào)整網(wǎng)絡(luò)模式屬于進(jìn)階配置我一般不輕易動(dòng)因?yàn)楦牧酥蟊緳C(jī)的訪問(wèn)路徑也可能跟著變等于拆東墻補(bǔ)西墻。多端口映射就重復(fù)寫-pwslc run --rm -d --name svc \ -p 8080:80 \ -p 8443:443 \ nginx:alpine容器端口那側(cè)必須是容器內(nèi)實(shí)際監(jiān)聽的端口寫錯(cuò)了不會(huì)報(bào)錯(cuò)只會(huì)一直連不上。我遇到過(guò)一次服務(wù)配置里監(jiān)聽的是 8080我映射的是 80查了半小時(shí)網(wǎng)絡(luò)配置最后發(fā)現(xiàn)是端口對(duì)不上?，F(xiàn)在的習(xí)慣是起完容器先wslc logs看一眼啟動(dòng)日志確認(rèn)服務(wù)真正監(jiān)聽在哪個(gè)端口再?zèng)Q定映射。3.4 掛載Windows 路徑與 Linux 路徑的映射陷阱掛載是最容易出問(wèn)題的地方?jīng)]有之一。核心矛盾在于容器的視角是 Linux 文件系統(tǒng)而你手上的代碼在 Windows 盤上中間隔著一層路徑翻譯。先說(shuō)路徑寫法。在 WSL 實(shí)例里Windows 的 C 盤被掛在/mnt/c所以你寫掛載源要用這個(gè)形式wslc run --rm -it -v /mnt/c/Users/me/project:/work alpine:latest /bin/sh看起來(lái)簡(jiǎn)單但坑在權(quán)限上。通過(guò)/mnt/c掛進(jìn)去的文件容器里看到的屬主和權(quán)限是由掛載層決定的不是原文件的真實(shí)屬性。結(jié)果就是容器里的非 root 用戶讀不了文件或者寫出來(lái)的文件在 Windows 側(cè)顯示權(quán)限異常。我遇到過(guò)幾次構(gòu)建過(guò)程報(bào)權(quán)限被拒絕最后定位到都是這個(gè)原因。繞開的方法有兩個(gè)。一是在容器里用 root 跑簡(jiǎn)單粗暴但會(huì)帶來(lái)產(chǎn)物權(quán)限問(wèn)題二是把項(xiàng)目代碼放到 WSL 實(shí)例自己的文件系統(tǒng)里比如/home/用戶名/project從這里掛載進(jìn)去權(quán)限語(yǔ)義就正常了。我現(xiàn)在統(tǒng)一用第二種雖然要多一步復(fù)制但省下的排障時(shí)間遠(yuǎn)超那點(diǎn)復(fù)制成本。還有一個(gè)隱蔽的陷阱是路徑大小寫。Windows 文件系統(tǒng)不區(qū)分大小寫Linux 區(qū)分。你的代碼里寫了import Config文件實(shí)際叫config.js在 Windows 上跑得好好的一進(jìn)容器就報(bào)找不到模塊。這類問(wèn)題在掛載/mnt/c時(shí)尤其容易冒出來(lái)因?yàn)閽燧d層會(huì)盡量兼容但容器內(nèi)的應(yīng)用未必買賬。構(gòu)建上下文同理后面還會(huì)提到。4. 自建鏡像構(gòu)建上下文、緩存層與報(bào)錯(cuò)對(duì)照4.1 構(gòu)建上下文與大小寫敏感的坑構(gòu)建鏡像時(shí)wslc build會(huì)把指定的目錄作為上下文打包送進(jìn)構(gòu)建過(guò)程。這里第一個(gè)決策點(diǎn)是上下文給多大。給整個(gè)項(xiàng)目根目錄是最常見的做法但如果根目錄下有node_modules、.git、構(gòu)建產(chǎn)物這類巨型目錄打包和傳輸會(huì)非常慢。解決辦法是寫一個(gè)忽略文件把不需要的路徑排掉# .dockerignore node_modules .git dist *.log這份忽略文件帶來(lái)的提速是數(shù)量級(jí)的。我在一個(gè)中等規(guī)模項(xiàng)目上做過(guò)對(duì)比加了忽略文件后構(gòu)建啟動(dòng)時(shí)間從四十多秒降到三秒。原因很簡(jiǎn)單上下文打包是同步操作文件越多越慢而且這些文件根本不會(huì)在構(gòu)建里用到。第二個(gè)決策點(diǎn)是路徑大小寫。構(gòu)建過(guò)程中的路徑解析遵循 Linux 規(guī)則嚴(yán)格區(qū)分大小寫。如果你的COPY指令寫的是COPY ./Src ./app而實(shí)際目錄叫src構(gòu)建會(huì)直接失敗并報(bào)找不到文件。這在從 Windows 遷移過(guò)來(lái)的項(xiàng)目里極其常見因?yàn)楸镜亻_發(fā)根本感知不到這個(gè)問(wèn)題。我的處理辦法是在構(gòu)建前跑一遍文件名清單和 Dockerfile 里的指令逐條比對(duì)。聽起來(lái)笨但比反復(fù)構(gòu)建試錯(cuò)快。4.2 多階段構(gòu)建與層緩存復(fù)用多階段構(gòu)建是控制鏡像體積最有效的手段邏輯是把編譯和運(yùn)行拆成兩個(gè)階段只把編譯產(chǎn)物帶進(jìn)最終鏡像。# 階段一構(gòu)建 FROM node:20-alpine AS builder WORKDIR /src COPY package*.json ./ RUN npm ci COPY . . RUN npm run build # 階段二運(yùn)行 FROM node:20-alpine WORKDIR /app COPY --frombuilder /src/dist ./dist COPY --frombuilder /src/node_modules ./node_modules EXPOSE 3000 CMD [node, dist/main.js]這樣寫的好處是最終鏡像里不含源碼、不含編譯工具鏈體積能小一半以上。我做過(guò)一個(gè)對(duì)照單階段鏡像 1.1G多階段降到 420M。層緩存的復(fù)用規(guī)則要理解清楚每條指令生成一層某層失效它之后的所有層都要重建。所以指令順序很關(guān)鍵——變化頻率低的東西放前面變化頻率高的放后面。上面的例子里先COPY package*.json再npm ci最后才COPY . .就是為了讓依賴安裝這一層在源碼變動(dòng)時(shí)仍然命中緩存。如果順序反過(guò)來(lái)每次改一行代碼都要重裝一遍依賴構(gòu)建時(shí)間從十幾秒變成幾分鐘。這里有個(gè)實(shí)操細(xì)節(jié)npm ci比npm install更適合構(gòu)建場(chǎng)景因?yàn)樗鼑?yán)格按鎖文件安裝結(jié)果可復(fù)現(xiàn)而且不會(huì)因?yàn)榘姹痉秶ヅ涞叫掳姹?。這一點(diǎn)在流水線上尤其重要我遇到過(guò)因?yàn)橐蕾囆“姹旧?jí)導(dǎo)致構(gòu)建產(chǎn)物行為變化的事故換成ci之后這類問(wèn)題基本消失。4.3 構(gòu)建失敗報(bào)錯(cuò)對(duì)照表構(gòu)建報(bào)錯(cuò)的信息量往往不大得靠經(jīng)驗(yàn)對(duì)照。我把常遇到的幾類整理成表報(bào)錯(cuò)關(guān)鍵詞大概率原因處理方向failed to compute cache key/not foundCOPY 源路徑寫錯(cuò)或大小寫不匹配核對(duì)上下文內(nèi)實(shí)際路徑與大小寫permission denied掛載目錄權(quán)限語(yǔ)義異常或容器內(nèi)用戶無(wú)權(quán)限改用實(shí)例內(nèi)路徑作為上下文或調(diào)整運(yùn)行用戶no space left on device虛擬磁盤空間耗盡或構(gòu)建緩存堆積清理緩存與懸空鏡像必要時(shí)壓縮磁盤exec format error鏡像架構(gòu)與當(dāng)前平臺(tái)不匹配確認(rèn)拉取的鏡像架構(gòu)標(biāo)簽network timeout/connection reset拉取基礎(chǔ)鏡像或依賴時(shí)網(wǎng)絡(luò)中斷改用離線導(dǎo)入或重試并延長(zhǎng)超時(shí)exit code: 137進(jìn)程被強(qiáng)制終止通常是內(nèi)存不足提高實(shí)例內(nèi)存上限或優(yōu)化構(gòu)建內(nèi)存占用表里最容易被誤判的是exit code: 137。很多人第一反應(yīng)是命令寫錯(cuò)了實(shí)際上是內(nèi)存超限被殺。構(gòu)建大型前端項(xiàng)目時(shí)尤其常見因?yàn)榇虬^(guò)程會(huì)吃很多內(nèi)存。我現(xiàn)在的做法是給實(shí)例分配足夠內(nèi)存同時(shí)在構(gòu)建命令里限制并發(fā)用時(shí)間換空間。exec format error也值得單獨(dú)說(shuō)。如果你在 ARM 架構(gòu)的機(jī)器上拉了一個(gè)只為 x86 構(gòu)建的鏡像就會(huì)撞到這個(gè)錯(cuò)。報(bào)錯(cuò)信息不會(huì)告訴你架構(gòu)不匹配只會(huì)說(shuō)格式錯(cuò)誤很容易往別處想。確認(rèn)方法是在拉取時(shí)顯式指定架構(gòu)標(biāo)簽或者查一下鏡像支持的平臺(tái)列表。5. 排障實(shí)錄五個(gè)報(bào)錯(cuò)從現(xiàn)象追到根因5.1 容器啟動(dòng)即退出日志一片空白現(xiàn)象wslc run -d之后wslc ps里看不到容器wslc ps -a能看到狀態(tài)是Exited (0)wslc logs什么都沒(méi)輸出。這條鏈路我是這么走的。第一步確認(rèn)容器是不是真的執(zhí)行了命令。用wslc inspect看容器的配置重點(diǎn)看Cmd和Entrypoint字段。有次發(fā)現(xiàn)鏡像里定義的入口腳本路徑不對(duì)容器啟動(dòng)后找不到命令直接以 0 退出日志自然是空的。第二步如果命令沒(méi)問(wèn)題就換成前臺(tái)模式跑把輸出直接打到終端wslc run --rm -it 鏡像 /bin/sh能進(jìn) shell 說(shuō)明鏡像本身沒(méi)壞問(wèn)題在啟動(dòng)命令上。這時(shí)候手動(dòng)執(zhí)行一遍原來(lái)的入口命令報(bào)錯(cuò)就出來(lái)了。第三步如果連 shell 都進(jìn)不去那就是鏡像或者運(yùn)行時(shí)的問(wèn)題。檢查wslc images里鏡像大小是否異常偏小——偏小通常意味著拉取中斷層不完整。刪掉重新拉一次。我在這個(gè)問(wèn)題上最深刻的一次教訓(xùn)是日志空白不等于沒(méi)有錯(cuò)誤很多時(shí)候是錯(cuò)誤發(fā)生在日志系統(tǒng)就緒之前。這時(shí)候inspect和前臺(tái)運(yùn)行比logs有用得多。5.2 端口被占用卻找不到進(jìn)程現(xiàn)象啟動(dòng)容器報(bào)port is already allocated但用netstat查那個(gè)端口什么也沒(méi)查到。根因通常有兩層。第一層是停止?fàn)顟B(tài)的容器仍然占著端口記錄。wslc ps -a會(huì)列出所有容器包括已經(jīng)退出的那些如果某個(gè)已退出的容器曾經(jīng)映射過(guò)這個(gè)端口記錄可能還在。處理辦法是把它徹底刪掉wslc rm -f 容器名第二層是實(shí)例內(nèi)的其他進(jìn)程占了端口但你在 Windows 側(cè)的 netstat 里看不到因?yàn)槟鞘菍?shí)例內(nèi)部的網(wǎng)絡(luò)命名空間。查這個(gè)要在實(shí)例里執(zhí)行ss -lntp | grep 8080我有一次就是卡在第二層在 Windows 側(cè)查了半天沒(méi)結(jié)果進(jìn)實(shí)例一查是個(gè)之前遺留的服務(wù)進(jìn)程還掛著。殺掉之后立刻正常。順著這個(gè)思路還能推出一條經(jīng)驗(yàn)端口沖突類問(wèn)題永遠(yuǎn)先在容器和實(shí)例這兩個(gè)層面查別一上來(lái)就懷疑系統(tǒng)?？鐚拥倪M(jìn)程視圖不互通是這類問(wèn)題的最大迷惑源。5.3 掛載后文件權(quán)限被改寫現(xiàn)象容器內(nèi)向掛載目錄寫文件寫出來(lái)的文件在 Windows 側(cè)打開提示權(quán)限異?；蛘呷萜鲀?nèi)的服務(wù)進(jìn)程報(bào)無(wú)權(quán)寫入。前面提過(guò)根因在掛載層的權(quán)限映射。這里補(bǔ)充具體的定位方法。先在容器內(nèi)看文件的實(shí)際屬主ls -ln /work如果顯示的數(shù)字 UID 和容器內(nèi)運(yùn)行用戶的 UID 對(duì)不上就是這個(gè)原因。解決辦法分兩種場(chǎng)景一種是開發(fā)調(diào)試圖省事直接在運(yùn)行命令里指定用戶wslc run --rm -it --user $(id -u):$(id -g) -v /home/me/project:/work alpine:latest /bin/sh這樣容器內(nèi)進(jìn)程的 UID 和掛載源屬主一致讀寫就不會(huì)沖突。另一種是構(gòu)建產(chǎn)物場(chǎng)景需要產(chǎn)物在 Windows 側(cè)能正常使用。這時(shí)候更穩(wěn)的做法是把構(gòu)建過(guò)程放在實(shí)例內(nèi)的路徑下完成最后再?gòu)?fù)制到 Windows 盤而不是直接往/mnt/c下寫。多一步復(fù)制省掉一堆權(quán)限糾紛。5.4 磁盤占用暴漲現(xiàn)象用了一陣子虛擬磁盤文件漲到幾十 G刪了鏡像也沒(méi)見變小。這里要理解虛擬磁盤的分配機(jī)制它是按需增長(zhǎng)的增長(zhǎng)后不會(huì)自動(dòng)收縮。刪文件只是把塊標(biāo)記為空閑文件本身的大小不變。所以要分兩步處理。第一步清掉容器側(cè)的無(wú)用數(shù)據(jù)wslc system prune -a --volumes這條命令會(huì)刪除所有停止的容器、未被引用的鏡像、構(gòu)建緩存和未使用的數(shù)據(jù)卷。執(zhí)行前務(wù)必確認(rèn)沒(méi)有還需要的東西——它不給撤銷機(jī)會(huì)。我第一次跑的時(shí)候手快把一個(gè)還在調(diào)試的容器刪了只能重來(lái)。第二步如果文件仍然很大做一次磁盤壓縮。先關(guān)閉所有實(shí)例再用系統(tǒng)工具壓縮虛擬磁盤文件。這一步耗時(shí)較長(zhǎng)取決于磁盤大小我一般放在下班前跑。日常預(yù)防更有效定期跑wslc system df看賬構(gòu)建緩存那一欄超過(guò)幾 G 就清一次。養(yǎng)成這個(gè)習(xí)慣之后我的磁盤再?zèng)]暴漲過(guò)。5.5 鏡像拉取超時(shí)的離線解法現(xiàn)象wslc pull卡住或者超時(shí)重試幾次都不行。網(wǎng)絡(luò)鏈路的排查我這里不多展開重點(diǎn)說(shuō)一條更可靠的替代路徑離線導(dǎo)入。思路是在能正常訪問(wèn)的環(huán)境里把鏡像導(dǎo)出成文件再拷到目標(biāo)機(jī)器導(dǎo)入。# 在可用環(huán)境導(dǎo)出 wslc pull nginx:alpine wslc save -o nginx-alpine.tar nginx:alpine # 在目標(biāo)環(huán)境導(dǎo)入 wslc load -i nginx-alpine.tar這條路徑的好處是完全不依賴構(gòu)建時(shí)的網(wǎng)絡(luò)適合內(nèi)網(wǎng)環(huán)境、演示現(xiàn)場(chǎng)這類網(wǎng)絡(luò)不確定的場(chǎng)景。代價(jià)是文件體積大傳輸要花時(shí)間。我現(xiàn)在的習(xí)慣是給常用基礎(chǔ)鏡像準(zhǔn)備一份離線包放在本地目錄里新機(jī)器上手先導(dǎo)入再慢慢拉其他東西。導(dǎo)出的時(shí)候注意別把一堆無(wú)關(guān)鏡像打進(jìn)去save是按鏡像逐個(gè)導(dǎo)的多寫幾個(gè)鏡像名會(huì)打成一個(gè)包體積翻倍。6. 長(zhǎng)期用下去資源邊界、清理節(jié)奏與工作流融合6.1 內(nèi)存和 CPU 的分配邊界WSL 實(shí)例默認(rèn)會(huì)按需吃內(nèi)存理論上限可以到宿主內(nèi)存的一多半。這在跑容器時(shí)會(huì)出問(wèn)題構(gòu)建一個(gè)大項(xiàng)目把內(nèi)存吃滿宿主開始卡頓甚至觸發(fā)系統(tǒng)級(jí)別的內(nèi)存回收構(gòu)建進(jìn)程被殺報(bào)一個(gè)毫無(wú)信息量的退出碼?？刂妻k法是寫一個(gè)配置文件給實(shí)例設(shè)上限。配置文件放在用戶目錄下內(nèi)容大致是[wsl2] memory8GB processors4 swap2GB數(shù)字按機(jī)器實(shí)際情況定。我的一般原則是給實(shí)例分配宿主內(nèi)存的一半處理器核數(shù)不超過(guò)物理核數(shù)減二留出余量給宿主側(cè)。這樣既夠容器跑又不至于把機(jī)器拖死。改完配置要重啟實(shí)例才生效wsl --shutdown這條命令會(huì)關(guān)閉所有實(shí)例包括正在跑容器的那些執(zhí)行前記得保存工作。另一個(gè)容易被忽略的點(diǎn)是交換空間。設(shè)了 swap 之后內(nèi)存壓力大時(shí)不會(huì)立刻殺進(jìn)程而是換到磁盤。代價(jià)是變慢。我在構(gòu)建場(chǎng)景下會(huì)關(guān)掉 swap讓內(nèi)存不足直接暴露出來(lái)比默默變慢好排查。6.2 清理節(jié)奏鏡像、容器、構(gòu)建緩存清理這件事與其等磁盤告警再動(dòng)手不如定個(gè)節(jié)奏。我的做法是分三檔日常檔每次調(diào)試結(jié)束跑一次輕量清理刪掉退出狀態(tài)的容器wslc container prune -f周檔清一次構(gòu)建緩存和懸空鏡像wslc image prune -f wslc builder prune -f月檔做一次全面盤點(diǎn)和磁盤壓縮。先看賬wslc system df然后按需清理最后壓縮虛擬磁盤文件。這里有個(gè)經(jīng)驗(yàn)不要用刪了再說(shuō)的心態(tài)清理。每次清理前先wslc images看一眼清單確認(rèn)沒(méi)有正在依賴的鏡像是懸空狀態(tài)——有些鏡像雖然當(dāng)前沒(méi)有容器引用但你可能下周還要用刪了還得重新拉。我吃過(guò)一次虧清理完第二天要演示結(jié)果鏡像沒(méi)了現(xiàn)場(chǎng)等了兩分鐘拉取非常尷尬。現(xiàn)在我給常用鏡像打上明確標(biāo)簽清理時(shí)按標(biāo)簽排除。6.3 與編輯器、腳本、流水線的銜接工具裝好只是開始真正提升效率的是把它嵌進(jìn)日常流程。編輯器側(cè)主流編輯器都有連接 WSL 實(shí)例的能力連上之后終端、文件瀏覽、調(diào)試都在實(shí)例內(nèi)進(jìn)行容器操作可以直接在集成終端里敲。這樣省掉了來(lái)回切窗口的動(dòng)作也避免了路徑寫錯(cuò)。腳本側(cè)我把高頻命令收進(jìn)一個(gè)入口腳本參數(shù)化處理。比如一個(gè)dev.sh接up、down、logs、rebuild四個(gè)子命令內(nèi)部封裝對(duì)應(yīng)的wslc調(diào)用。好處是團(tuán)隊(duì)里每個(gè)人敲的命令一樣不會(huì)出現(xiàn)你這臺(tái)機(jī)器上是這么跑的這種分歧。#!/usr/bin/env bash set -euo pipefail case ${1:-} in up) wslc run -d --name app -p 3000:3000 -v $PWD:/app app:dev ;; down) wslc rm -f app ;; logs) wslc logs -f app ;; rebuild) wslc build -t app:dev . ;; *) echo usage: $0 {up|down|logs|rebuild} exit 1 ;; esacset -euo pipefail這行別省它能讓腳本在任一步失敗時(shí)立刻停下而不是帶著錯(cuò)誤狀態(tài)繼續(xù)往下跑。我早期寫的腳本沒(méi)加這行出現(xiàn)過(guò)構(gòu)建失敗但容器還是啟動(dòng)了舊鏡像的假成功排查起來(lái)很費(fèi)勁。流水線側(cè)關(guān)鍵在于本地和遠(yuǎn)端的構(gòu)建方式保持一致。既然本地用 wslc 構(gòu)建那構(gòu)建文件本身就得是標(biāo)準(zhǔn)格式不要摻入本地特有的路徑或參數(shù)。這一點(diǎn)做到了本地能過(guò)的構(gòu)建換到別的環(huán)境大概率也能過(guò)。6.4 升級(jí)與回滾的注意點(diǎn)wslc 還在演進(jìn)升級(jí)是常態(tài)。升級(jí)前有兩件事要做一是記下當(dāng)前版本號(hào)二是確認(rèn)關(guān)鍵鏡像和數(shù)據(jù)卷有備份或者能重建。版本號(hào)記錄很簡(jiǎn)單wslc version把它寫進(jìn)項(xiàng)目文檔的環(huán)境說(shuō)明里。出問(wèn)題時(shí)這個(gè)數(shù)字是你判斷是不是版本變化導(dǎo)致的的第一依據(jù)。數(shù)據(jù)方面容器本身是無(wú)狀態(tài)的刪了能重建真正要保的是數(shù)據(jù)卷和自定義鏡像。數(shù)據(jù)卷可以導(dǎo)出成歸檔文件自定義鏡像可以用save導(dǎo)成 tar 包。我一般在下一次大版本升級(jí)前做一次這兩個(gè)動(dòng)作成本幾分鐘換來(lái)的是可以隨時(shí)回退。升級(jí)之后別急著干活先跑一遍第 2.4 節(jié)那套三步驗(yàn)證。我遇到過(guò)一次升級(jí)后端口映射行為變化驗(yàn)證時(shí)發(fā)現(xiàn)了沒(méi)影響到正式使用。如果不驗(yàn)證直接上很可能在關(guān)鍵時(shí)刻才發(fā)現(xiàn)問(wèn)題?；貪L的路徑要提前想好。如果升級(jí)后出現(xiàn)無(wú)法繞過(guò)的問(wèn)題卸載新版、裝回舊版、重新導(dǎo)入鏡像和數(shù)據(jù)這條鏈路能不能走通最好在不出問(wèn)題的時(shí)候演練一次。聽起來(lái)麻煩但真出事的時(shí)候手上有演練過(guò)的步驟和現(xiàn)場(chǎng)現(xiàn)編步驟是完全兩種體驗(yàn)。最后分享一個(gè)我自己養(yǎng)成的小習(xí)慣每次環(huán)境有較大變動(dòng)升級(jí)、改配置、換機(jī)器就在項(xiàng)目文檔里加一行變更記錄寫上日期、做了什么、驗(yàn)證結(jié)果。幾個(gè)月后回頭看這些記錄能幫你快速定位這個(gè)環(huán)境是從什么時(shí)候開始不一樣的。這個(gè)東西不花時(shí)間但價(jià)值很高。