آموزش رایگان Node.js در ویندوز؛ از نصب تا ساخت API

بخش بزرگی از خطاهای شروع کار، از زبان جاوااسکریپت نیست؛ دستور در محیط دیگری اجرا شده، Node از نصب دیگری آمده یا فایل‌ها در مسیری متفاوت قرار دارند. پیش از دانلود هر ابزار، یک تصمیم روشن بگیرید: مسیر اصلی این دوره، اجرای مستقیم Node.js در ویندوز و استفاده از PowerShell است. WSL مسیر اختیاری برای کار در محیط لینوکس روی ویندوز است. این دو روش را می‌توان آگاهانه کنار هم داشت، اما برای نخستین پروژه، رفت‌وآمد بی‌برنامه میان آن‌ها عیب‌یابی را دشوار می‌کند.

ترمینال پنجره است؛ شل فرمان را تفسیر می‌کند

Windows Terminal یا پنل Terminal در VS Code فضایی برای نمایش ورودی و خروجی است. PowerShell، Command Prompt و Bash نمونهٔ شل‌اند؛ شل است که معنی دستور و شیوهٔ نوشتن متغیر را تعیین می‌کند. نوشتن $env:PORT در PowerShell و export PORT در Bash دو دستور متعلق به دو محیط‌اند. نام پنجره یا ظاهر تیره، محیط را مشخص نمی‌کند. هنگام گزارش خطا، نام شل و مسیر کاری را هم ثبت کنید تا یک راه‌حل مخصوص Bash به اشتباه در PowerShell اجرا نشود.

$PSVersionTable.PSVersion
Get-Location
Get-Command node -ErrorAction SilentlyContinue

دستور اول نسخهٔ PowerShell و دستور دوم پوشهٔ جاری را نشان می‌دهد. دستور سوم، اگر Node در دسترس باشد، فرمان انتخاب‌شده را گزارش می‌کند؛ پیش از نصب ممکن است خروجی نداشته باشد. این رفتار به‌تنهایی مشکل نیست. در ویندوز PowerShell قدیمی‌تر هم بسیاری از دستورهای پایهٔ درس اجرا می‌شوند، ولی آموزش بر دستورهای سازگار و ساده تکیه دارد. برای امکانات خاص یک نسخه، مستندات همان نسخه را بررسی کنید و همهٔ دستورهای اینترنت را بدون شناخت اجرا نکنید.

روش مستقیم یا WSL2؛ انتخاب بر اساس کار

برای دانشجویی که نخستین API محلی را می‌سازد، نصب مستقیم روی یک ویندوز پشتیبانی‌شده، تعداد تصمیم‌های آغازین را کم می‌کند. با فایل‌های ویندوز، PowerShell و نصب Node مخصوص ویندوز کار می‌کنید. اگر محیط استقرار آینده لینوکس است، ابزارهای ویژهٔ لینوکس لازم دارید یا تیم شما روی WSL استاندارد شده، WSL2 گزینهٔ قابل بررسی است. در آن حالت، Node و مدیر نسخه باید در همان توزیع لینوکس نصب شوند و دستورهای Bash مربوط به همان محیط خواهند بود.

محل پروژه را هم با محیط هماهنگ نگه دارید: برای مسیر مستقیم، پوشه‌ای در فضای کاربر ویندوز؛ برای ابزار لینوکسی در WSL، معمولاً پوشه‌ای در فایل‌سیستم همان توزیع. کپی‌کردن node_modules میان ویندوز و لینوکس راه مناسبی برای جابه‌جایی پروژه نیست؛ بعضی بسته‌ها فایل بومی وابسته به سیستم دارند. کد و فایل قفل را منتقل می‌کنیم و وابستگی را در مقصد با روش درست بازسازی می‌کنیم. جزئیات npm و فایل قفل در فصل بعد می‌آید.

نسخهٔ سیستم عامل و معماری را پیش از دانلود ببینید

در Settings > System > About، نام و نسخهٔ ویندوز و System type را بررسی کنید. این مسیر برای ویندوز ۱۱ طراحی شده است؛ برای دستگاه‌های دیگر، صفحهٔ پشتیبانی نسخهٔ انتخابی Node و سیاست پشتیبانی سیستم عامل را ببینید. صرف وجود یک فایل نصب قدیمی، به معنی امن یا پشتیبانی‌شده‌بودن ترکیب آن با سیستم شما نیست. این دوره برای اجرا روی سیستم عامل منقضی‌شده، تضمین سازگاری نمی‌دهد و توصیه نمی‌کند صرفاً برای اجرای کد، نسخهٔ فاقد پشتیبانی نصب کنید.

در دستگاه‌های معمول مبتنی بر پردازندهٔ ۶۴بیتی Intel یا AMD، گزینهٔ x64 رایج است. دستگاه Windows on ARM ممکن است به نسخهٔ arm64 نیاز داشته باشد. براساس System type و راهنمای دانلود رسمی انتخاب کنید؛ اندازهٔ حافظه یا اسم تجاری لپ‌تاپ، معیار کافی نیست. پس از نصب، process.arch معماری باینری Node در حال اجرا را نشان می‌دهد؛ این خروجی را با معماری فیزیکی همهٔ قطعات دستگاه یکی ندانید، چون اجرا در لایهٔ سازگاری ممکن است تفاوت ایجاد کند.

node -p "process.platform"
node -p "process.arch"
node -p "process.execPath"

در نصب بومی ویندوز، platform معمولاً win32 است؛ این نام تاریخی به معنی ۳۲بیتی‌بودن برنامه نیست. معماری جداگانه در خروجی بعدی دیده می‌شود. در Node نصب‌شده داخل WSL، مقدار platform، linux خواهد بود. execPath مسیر اجرایی واقعی را نشان می‌دهد و برای یافتن تداخل نصب‌ها مفید است. این سه خروجی را پس از نصب در یادداشت محیط ثبت کنید تا بعداً مشخص باشد آزمون را با کدام Node اجرا کرده‌اید.

حداقل ابزار لازم و ابزارهایی که می‌توانند صبر کنند

برای شروع، Node.js همراه npm، یک ویرایشگر مانند VS Code و PowerShell کافی‌اند. مرورگر برای مشاهدهٔ پاسخ و ابزارهای توسعه مفید است. Git در کار تیمی و ثبت تغییرها ارزش دارد، اما شرط اجرای فایل نخست نیست. Postman یک کلاینت اختیاری API است؛ پروژه را با ابزارهای سادهٔ سیستم نیز می‌آزماییم. Docker، پایگاه داده و مجموعهٔ C++ Build Tools را از ابتدای کار نصب اجباری نکنید. اگر بعدها یک وابستگی بومی به آن‌ها نیاز داشت، خطای همان وابستگی و راهنمای رسمی را بررسی کنید.

تمرین انتخاب محیط و پاسخ

فرض کنید همکار شما دستور export را برای تعیین یک متغیر فرستاده و شما در PowerShell خطا گرفته‌اید. پاسخ درست این نیست که همهٔ ابزارها را دوباره نصب کنید؛ ابتدا شل را تشخیص دهید و شکل معادل متغیر را از درس پیکربندی بخوانید. تمرین دوم: Node در ترمینال WSL مقدار linux و در PowerShell مقدار win32 می‌دهد. این الزاماً تناقض نیست؛ دو محیط اجرا دارید. معیار تحویل، یک یادداشت کوتاه شامل انتخاب مسیر، نام شل، نسخهٔ سیستم عامل، معماری و علت انتخاب است.

ابزارها و منابع رسمی

انتخاب محیط ویندوز: https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows
مسیر اختیاری WSL2: https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl
Windows Terminal: https://learn.microsoft.com/en-us/windows/terminal/
مشخصات فرایند Node: https://nodejs.org/api/process.html

متن فارسی، سناریوها و مثال‌ها: تألیف مستقل تحریریه درس‌آوند.