WSL2 برای کاربرهای ویندوز

توی این درس یاد می‌گیری WSL2 (Windows Subsystem for Linux، یعنی «زیرسیستم ویندوز برای لینوکس») چیست و چرا داکر روی ویندوز به آن نیاز دارد، چطور با یک دستور Ubuntu را نصب و درستی نصب را بررسی کنی، فایل‌ها بین ویندوز و لینوکس چطور دیده می‌شوند، و چرا پروژه‌ی داکرت را باید داخل فایل‌سیستم لینوکس نگه داری، نه روی درایو C:.

اگر ویندوز نداری

این درس فقط برای کاربران ویندوز است. اگر مک یا لینوکس داری، می‌توانی مستقیم بروی سراغ درس‌های بعد.

درباره‌ی صحت دستورهای این درس

سیستم‌عاملی که دستورهای این دوره روی آن آزمایش می‌شود ویندوز نیست. پس دستورهای PowerShell و تنظیمات Docker Desktop در این درس را با مستندات رسمی مایکروسافت و داکر تطبیق داده‌ام، و خروجی‌هایی که برچسب «نمونه» دارند اجرای مستقیم نیستند. بخش‌هایی که داخل خود Ubuntu اجرا می‌شوند (مثال‌های ۴ و ۵) روی یک Ubuntu واقعی تست شده‌اند.

چرا داکر روی ویندوز به WSL نیاز دارد؟

داکر برای اجرای کانتینر از ویژگی‌های هسته‌ی لینوکس (namespace و cgroup) استفاده می‌کند. ویندوز این هسته را ندارد. پس داکر روی ویندوز باید یک لینوکس واقعی را جایی در پس‌زمینه اجرا کند. WSL2 همین کار را برایش انجام می‌دهد: یک هسته‌ی واقعی لینوکس داخل یک ماشین مجازی سبک که ویندوز آن را به‌صورت خودکار مدیریت می‌کند.

مثل این است که داخل خانه‌ات (ویندوز) یک اتاق مهمان داری که کاملاً به سبک لینوکس چیده شده. لازم نیست از خانه بیرون بروی؛ درِ اتاق همان‌جا توی خانه است. و برای تو هم فقط همین اتاق مهم است: تمام کارهای این دوره را در آن اتاق (ترمینال Ubuntu) انجام می‌دهی.

◆سناریوی واقعی

فرض کن توی یک شرکت کار می‌کنی که همه‌ی لپ‌تاپ‌ها ویندوزی‌اند ولی سرورها لینوکس. همکارت می‌گوید: «پروژه را بگیر، با داکر بالا بیاور.» تو پروژه را روی C:\Users\ali\shop می‌گذاری و داکر را اجرا می‌کنی. کار می‌کند، ولی npm install و build به‌طرز عجیبی کند است، کندتر از چیزی که روی لپ‌تاپ همکارت می‌دیدی.

همکارت یک نگاه می‌اندازد و می‌پرسد: «پروژه را کجا گذاشته‌ای؟» جواب: روی C:. او می‌گوید پروژه را داخل ترمینال Ubuntu و زیر ~/shop بگذار. بعد از جابه‌جایی همه‌چیز همان سرعتی را دارد که انتظار داشتی. این درس دقیقاً توضیح می‌دهد چرا.

WSL چه تکه‌هایی دارد؟

WSL 2: ویندوز یک ماشین مجازی سبک با هسته‌ی لینوکس مدیریت می‌کند. توزیع‌ها (Ubuntu و docker-desktop) داخل آن ایزوله‌اند و کانتینرهای داکر هم همان‌جا اجرا می‌شوند.

نکته‌ی مهم از نمودار: Docker Desktop برای خودش یک توزیع جدا به اسم docker-desktop می‌سازد، که از Ubuntu تو جداست. به این دلیل داکر داخل Ubuntu خودت کار می‌کند (از راه یک «یکپارچه‌سازی» که بعداً فعال می‌کنیم)، نه اینکه Ubuntu تو خودش موتور داکر باشد.

مثال‌های عملی

مثال ۱: ویندوزت پشتیبانی می‌کند؟ (نمونه)

طبق مستندات مایکروسافت، برای دستور wsl --install به Windows 10 نسخه‌ی 2004 به بالا (Build 19041 و بالاتر) یا Windows 11 نیاز داری. نسخه‌ات را از اینجا ببین: کلیدهای Win + R را بزن، بنویس winver و Enter کن. یا در Command Prompt:

ver

خروجی (نمونه)

Microsoft Windows [Version 10.0.22631.3007]

عدد بعد از 10.0. شماره‌ی Build است (در نمونه: 22631). اگر از 19041 کمتر باشد، باید اول ویندوز را به‌روز کنی.

مثال ۲: نصب WSL و Ubuntu با یک دستور

از منوی Start، PowerShell را پیدا کن، روی آن راست‌کلیک کن و Run as administrator را بزن. بعد:

wsl --install

این دستور هر چیزی که WSL لازم دارد را فعال می‌کند و Ubuntu را به‌عنوان توزیع پیش‌فرض نصب می‌کند. چند پیام پیشرفت می‌بینی (خروجی دقیقش با نسخه‌ی ویندوز فرق می‌کند). وقتی تمام شد، ویندوز را ری‌استارت کن. بعد از ری‌استارت پنجره‌ی Ubuntu خودش باز می‌شود و چند دقیقه صبر می‌خواهد؛ فقط بار اول طول می‌کشد. بعد یک username و password می‌خواهد. این‌ها مخصوص لینوکس‌اند و به حساب ویندوزت ربطی ندارند. موقع تایپ رمز چیزی نشان داده نمی‌شود، و این عادی است.

اگر به‌جای نصب، متن راهنما چاپ شد

طبق مستندات مایکروسافت، wsl --install فقط وقتی کار می‌کند که WSL اصلاً نصب نباشد. اگر متن راهنما دیدی، فهرست توزیع‌ها را بگیر و اسم یکی را مستقیم بده:

wsl --list --online
wsl --install -d Ubuntu-24.04

(اسم دقیق را از ستون NAME همان فهرست بردار.) اگر نصب روی ۰٪ گیر کرد: wsl --install --web-download -d Ubuntu-24.04.

مثال ۳: درست نصب شده؟ نسخه‌ی ۲ است؟ (نمونه)

wsl -l -v

خروجی (نمونه)

  NAME      STATE           VERSION
* Ubuntu    Running         2

باید زیر ستون VERSION عدد ۲ را ببینی. ستاره یعنی توزیع پیش‌فرض. -l مخفف --list و -v مخفف --verbose است. اگر عدد ۱ بود، به‌روزش کن:

wsl --set-version Ubuntu 2
wsl --set-default-version 2

دستور اول Ubuntu را به WSL 2 می‌برد و دومی نسخه‌ی پیش‌فرض برای توزیع‌های بعدی را ۲ می‌کند. برای به‌روز نگه داشتن خود WSL:

wsl --update

⚡ بررسی سریع

در wsl -l -v کدام ستون نسخه‌ی WSL را نشان می‌دهد؟

NAMESTATEستاره‌ی اول خطVERSION

مثال ۴: داخل Ubuntu، یک پروژه‌ی تازه (اجرای واقعی)

پنجره‌ی Ubuntu را باز کن (از Start یا با تایپ wsl در PowerShell). حالا داخل لینوکس هستی. پروژه را زیر پوشه‌ی home بساز:

cd ~
mkdir -p projects/myapp
cd projects/myapp
pwd

خروجی

/home/ali/projects/myapp

echo "hello from wsl" > hello.txt
ls -la
cat hello.txt

خروجی

total 12
drwxr-xr-x 2 ali ali 4096 Oct  3 08:11 .
drwxr-xr-x 3 ali ali 4096 Oct  3 08:11 ..
-rw-r--r-- 1 ali ali   15 Oct  3 08:11 hello.txt
hello from wsl

مسیر با /home/ali شروع می‌شود، یعنی روی فایل‌سیستم لینوکس هستی. همین‌جا باید پروژه‌های داکرت را بسازی. (برای آشنایی با ~، cd و ls به مرور لینوکس برگرد.)

مثال ۵: فایل‌ها بین دو دنیا

ویندوز و لینوکس هر کدام فایل‌سیستم خودشان را دارند و بین‌شان پل هست:

دو فایل‌سیستم: ویندوز (C:) و لینوکس (/home). هر کدام از دیگری هم قابل دیدن است، ولی رد شدن از مرز کند است.

دیدن فایل‌های لینوکس از ویندوز: از داخل Ubuntu، پوشه‌ی فعلی را در File Explorer باز کن (نقطه‌ی آخر را فراموش نکن):

explorer.exe .

یا در نوار آدرس File Explorer بنویس \\wsl$ تا همه‌ی توزیع‌ها و فایل‌سیستم‌هایشان را ببینی. (این دستور را مایکروسافت در مستنداتش آورده؛ چون روی ویندوز اجرا می‌شود، اینجا خروجی ندارد.)

دیدن فایل‌های ویندوز از لینوکس: درایو C: زیر /mnt/c mount می‌شود. مسیر C:\Users\ali\Project در Ubuntu می‌شود /mnt/c/Users/ali/Project. هر وقت /mnt/ را در مسیر دیدی، یعنی از یک درایو ویندوز استفاده می‌کنی. روی یک Ubuntu معمولی (مثل سیستم تستی که من داشتم) این پوشه خالی است:

ls /mnt

(خروجی خالی است، چون آن Ubuntu روی ویندوز نبود؛ روی WSL، c را اینجا می‌بینی.)

⚡ بررسی سریع

پروژه‌ی داکرت را کجا بگذاری تا سریع‌تر باشد؟

/mnt/c/Users/ali/Project~/projects/myapp (فایل‌سیستم لینوکس)روی Desktop ویندوزروی فلش

مثال ۶: اجرای لینوکس از PowerShell (نمونه)

نیازی نیست همیشه داخل Ubuntu باشی. می‌توانی از PowerShell هم یک دستور لینوکسی بزنی:

wsl pwd
wsl ls -la

دستور بعد از wsl در توزیع پیش‌فرض اجرا می‌شود و با همان پوشه‌ای شروع می‌کند که در PowerShell هستی (برای همین wsl pwd مسیر ویندوزی‌ات را به شکل /mnt/c/... نشان می‌دهد). مایکروسافت این‌ها را هم نشان داده:

wsl ls -la | findstr "git"

که خروجی ls -la لینوکس را به findstr ویندوز می‌دهد.

مثال ۷: Docker Desktop را به Ubuntu وصل کن

وقتی Docker Desktop را نصب کردی (درس نصب داکر)، طبق مستندات داکر:

1. Docker Desktop را باز کن، به Settings برو و گزینه‌ی Use WSL 2 based engine را روشن کن.
2. در Settings ← Resources ← WSL Integration، Ubuntu خودت را روشن کن. (طبق مستندات داکر، برای Ubuntu پیش‌فرض این گزینه خودکار روشن است.)
3. داخل ترمینال Ubuntu:

docker version --format 'Client: {{.Client.Os}}  Server: {{.Server.Os}}'

خروجی (نمونه)

Client: linux  Server: linux

اگر این‌جا هر دو linux بود، یعنی از داخل Ubuntu مستقیم با موتور داکر کار می‌کنی. (نصب کامل Docker Desktop در درس نصب داکر می‌آید.)

پشت پرده: WSL2 چطور کار می‌کند؟

یک ماشین مجازی سبک با هسته‌ی واقعی

مستندات مایکروسافت می‌گوید WSL 2 «یک هسته‌ی واقعی لینوکس را داخل یک ماشین مجازی سبک (lightweight utility VM) اجرا می‌کند». این هسته را خود مایکروسافت از شاخه‌ی پایدار kernel.org می‌سازد و با Windows Update به‌روز می‌شود، پس خودت مدیریتش نمی‌کنی. توزیع‌ها (مثل Ubuntu) به‌صورت ایزوله داخل همین ماشین مجازی اجرا می‌شوند. همین هسته‌ی واقعی است که اجرای کانتینر داکر را ممکن می‌کند.

WSL1 چه بود؟

نسخه‌ی اول هسته‌ی لینوکس نداشت و دستورهای سیستمی لینوکس را به ویندوز «ترجمه» می‌کرد. برای همین سازگاری کامل نبود و داکر روی آن کار نمی‌کرد. WSL2 با «سازگاری کامل system call ها» این را حل کرد.

شبکه: NAT

طبق مایکروسافت، WSL 2 یک ماشین مجازی Hyper-V است و از یک شبکه‌ی NAT استفاده می‌کند (نه bridged)، پس آدرس IP لینوکس با هر ری‌استارت ممکن است عوض شود. جزئیات شبکه‌ی داکر را در درس‌های شبکه می‌بینی.

جدول‌های مرجع

WSL 1 در برابر WSL 2 (بر اساس جدول مایکروسافت)

ویژگی	WSL 1	WSL 2
هسته‌ی کامل لینوکس	ندارد	دارد
سازگاری کامل system call	ندارد	دارد
ماشین مجازی مدیریت‌شده	ندارد	دارد
پشتیبانی از systemd	ندارد	دارد
سرعت فایل بین ویندوز و لینوکس	بهتر	کندتر
اجرای Docker	نمی‌شود	می‌شود

دستورهای مدیریتی (در PowerShell)

دستور	کاری که می‌کند
wsl --install	نصب WSL و Ubuntu
wsl --list --online	فهرست توزیع‌های قابل نصب
wsl -l -v	توزیع‌های نصب‌شده، وضعیت و نسخه
wsl --set-default-version 2	نسخه‌ی پیش‌فرض را ۲ می‌کند
wsl --set-version Ubuntu 2	توزیع Ubuntu را به WSL 2 می‌برد
wsl --update	به‌روزرسانی WSL
wsl --shutdown	خاموش کردن همه‌ی توزیع‌ها و ماشین مجازی
wsl --terminate Ubuntu	خاموش کردن فقط یک توزیع
wsl --set-default Ubuntu	تغییر توزیع پیش‌فرض

فایل‌ها: کجا نگه دارم؟

مسیر	معنی	برای پروژه‌ی داکر؟
/home/ali/... (یعنی ~/...)	فایل‌سیستم لینوکس	بله (پیشنهاد مایکروسافت و داکر)
/mnt/c/Users/ali/...	درایو C ویندوز	نه؛ کندتر است
\\wsl$\Ubuntu\home\ali	همان فایل‌های لینوکس، از دید ویندوز	فقط برای دیدن و کپی

قاعده‌ی ساده

فایل‌ها را کنار ابزاری نگه دار که با آن‌ها کار می‌کند. ابزار داکر داخل لینوکس است، پس پروژه هم داخل لینوکس (~). طبق مستندات مایکروسافت، رد شدن مکرر از مرز دو فایل‌سیستم مهم‌ترین عامل کندی است، و برای بیشترین سرعت باید فایل‌ها داخل فایل‌سیستم همان محیطی باشند که در آن کار می‌کنی.

اشتباهات رایج

۱) پروژه را روی C: گذاشتن

نشانه‌اش خطا نیست؛ کندی است: کارهایی که فایل‌های زیادی را می‌خوانند (مثل npm install و build) کند می‌شوند. راه‌حل: پروژه را داخل ~ (مثلاً ~/projects/myapp) بساز. اگر فایل‌هایت روی ویندوز است، آن‌ها را به ~ کپی کن (cp -r /mnt/c/Users/ali/Project ~/projects/).

۲) فراموش کردن ری‌استارت

بعد از wsl --install، تا ویندوز را ری‌استارت نکنی نصب کامل نمی‌شود. راه‌حل: ری‌استارت کن، بعد Ubuntu را باز کن.

۳) اجرا نکردن PowerShell به‌عنوان Administrator

دستور نصب با دسترسی کامل لازم است. راه‌حل: روی PowerShell راست‌کلیک و Run as administrator.

۴) خطای فعال نبودن مجازی‌سازی

اگر نصب با پیامی مثل این متوقف شد:

خطا (طبق مستندات مایکروسافت)

Error: 0x80370102 The virtual machine could not be started because a required feature is not installed.

مایکروسافت می‌گوید باید Virtual Machine Platform (از Windows Features) را روشن کنی و مطمئن شوی مجازی‌سازی (virtualization) در BIOS فعال است (روش دقیقش بسته به سازنده‌ی لپ‌تاپ فرق می‌کند). بعد از روشن کردن Virtual Machine Platform، ویندوز را ری‌استارت کن. اگر ویندوز خودش روی یک ماشین مجازی اجرا می‌شود، باید nested virtualization را هم روشن کنی. همچنین مایکروسافت می‌گوید CPU باید ویژگی SLAT را داشته باشد؛ CPUهای خیلی قدیمی (مثل Core 2 Duo) WSL2 را اجرا نمی‌کنند.

۵) قاطی کردن PowerShell و Ubuntu

دستورهای wsl ... را در PowerShell می‌زنی و دستورهای لینوکسی (ls، sudo) را داخل Ubuntu. پایین prompt را نگاه کن: PS C:\> یعنی PowerShell و ali@...:~$ یعنی لینوکس.

تمرین

✎ تمرینآسان

در PowerShell با یک دستور بفهم Ubuntu تو با کدام نسخه‌ی WSL کار می‌کند. چه چیزی در خروجی باید ببینی؟

دیدن جواب

wsl -l -v

زیر ستون VERSION باید عدد 2 باشد. (فقط مستندات تأیید می‌کند؛ این دستور روی ویندوز اجرا می‌شود.)

✎ تمرینمتوسط

داخل Ubuntu یک پروژه‌ی ~/projects/hello بساز که فایلی به اسم index.js با محتوای console.log('hi') داشته باشد. ثابت کن مسیرش داخل فایل‌سیستم لینوکس است، نه /mnt/.

دیدن جواب

mkdir -p ~/projects/hello && cd ~/projects/hello
echo "console.log('hi')" > index.js
ls -l
pwd

خروجی

total 4
-rw-r--r-- 1 ali ali 18 Oct  3 08:11 index.js
/home/ali/projects/hello

مسیر با /home شروع می‌شود (نه /mnt/c/...)، پس روی فایل‌سیستم لینوکس است.

✎ تمرینسخت

توزیع Ubuntu تو با wsl -l -v عدد 1 را نشان می‌دهد و Docker Desktop شکایت می‌کند. با دستورهای PowerShell آن را درست کن و کاری کن توزیع‌های تازه هم از اول WSL 2 باشند. بعد توضیح بده چرا پروژه‌ات باید زیر ~ باشد.

دیدن جواب

wsl --set-version Ubuntu 2
wsl --set-default-version 2
wsl -l -v

دستور اول Ubuntu را از WSL 1 به WSL 2 می‌برد (ممکن است زمان‌بر باشد؛ مایکروسافت توصیه می‌کند قبلش از فایل‌های بزرگ بکاپ بگیری)، دومی نسخه‌ی پیش‌فرض توزیع‌های بعدی را ۲ می‌کند و سومی را برای بررسی می‌زنیم؛ حالا باید VERSION برابر 2 باشد.

چرا زیر ~؟ چون ابزارهای داکر داخل لینوکس اجرا می‌شوند و طبق مستندات مایکروسافت برای بیشترین سرعت، فایل‌ها باید داخل فایل‌سیستم همان محیط باشند؛ دسترسی از لینوکس به /mnt/c/... از مرز دو فایل‌سیستم عبور می‌کند و کندتر است.

آزمونک

؟ آزمونک

1. چرا داکر روی ویندوز به WSL2 نیاز دارد؟

   چون کانتینرها به هسته‌ی لینوکس نیاز دارند و WSL2 یک هسته‌ی واقعی لینوکس فراهم می‌کندچون ویندوز نمی‌تواند برنامه اجرا کندچون WSL2 اینترنت را سریع‌تر می‌کندچون داکر فقط با PowerShell کار می‌کند

2. از خروجی «wsl -l -v» چطور می‌فهمی توزیعت با WSL 2 کار می‌کند؟

   ستاره کنار اسمستون STATE برابر Running استاسم توزیع Ubuntu استستون VERSION برابر 2 است

3. پروژه‌ی داکرت را کجا نگه داری؟

   ~/projects/myapp داخل Ubuntu/mnt/c/Users/ali/ProjectC:\Users\ali\Projectروی Desktop ویندوز

4. برای دیدن پوشه‌ی فعلی Ubuntu در File Explorer ویندوز چه دستوری می‌زنی؟

   explorer.exe .ls /mnt/cwsl --shutdowncd C:\

5. پیام «0x80370102 ... a required feature is not installed» بیشتر یعنی چه؟

   Ubuntu خراب استرمز لینوکس اشتباه استVirtual Machine Platform یا مجازی‌سازی در BIOS فعال نیستپروژه روی /mnt است

جمع‌بندی

• داکر کانتینر را با هسته‌ی لینوکس اجرا می‌کند؛ روی ویندوز، WSL2 این هسته را داخل یک ماشین مجازی سبک فراهم می‌کند.
• wsl --install (در PowerShell با دسترسی Administrator) WSL و Ubuntu را نصب می‌کند؛ بعدش ری‌استارت لازم است و در اولین ورود یک username و password لینوکسی می‌سازی.
• با wsl -l -v بررسی کن ستون VERSION برابر 2 باشد.
• ویندوز و لینوکس دو فایل‌سیستم دارند: C: و /mnt/c در برابر /home/.... با explorer.exe . و \\wsl$ از ویندوز فایل‌های لینوکس را می‌بینی.
• پروژه‌ی داکر را زیر ~ در لینوکس نگه دار، نه روی /mnt/c.
• Docker Desktop برای خودش توزیع docker-desktop دارد و باید در Settings ← Resources ← WSL Integration برای Ubuntu روشن باشد.

⌘ برگه‌ی تقلب این درس (PowerShell و لینوکس)

دستور	کاری که می‌کند
wsl --install	نصب WSL و Ubuntu (PowerShell ادمین، بعدش ری‌استارت)
wsl --list --online	فهرست توزیع‌های قابل نصب
wsl --install -d Ubuntu-24.04	نصب یک توزیع مشخص
wsl -l -v	توزیع‌ها، وضعیت و نسخه (VERSION باید 2 باشد)
wsl --set-version Ubuntu 2	ارتقای Ubuntu به WSL 2
wsl --set-default-version 2	نسخه‌ی پیش‌فرض توزیع‌های تازه
wsl --update	به‌روزرسانی WSL
wsl --shutdown	خاموش کردن همه‌ی توزیع‌ها
wsl <command>	اجرای یک دستور لینوکسی از PowerShell
explorer.exe .	باز کردن پوشه‌ی فعلی Ubuntu در File Explorer
cd ~ && mkdir -p projects/myapp	ساختن پروژه داخل فایل‌سیستم لینوکس
pwd	مطمئن شدن مسیر با /home شروع می‌شود، نه /mnt

در درس بعد وارد خود داکر می‌شویم: «داکر چیست؟»