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

وقتی پروژه را به همکارتان می‌دهید، گفتن «همان فرمانی که دیروز زدم» کافی نیست. باید نقطهٔ شروع، روش آزمون و نسخهٔ مورد انتظار روشن باشد. package.json برای ثبت این قرارداد به کار می‌آید. این فایل خود برنامه نیست و وجودش هم به معنی نیاز به نصب صدها بسته نیست. در این درس یک برنامهٔ محلی بدون وابستگی شخص ثالث می‌سازیم؛ npm نقش اجرای فرمان‌های نام‌گذاری‌شده را دارد.

در پوشه‌ای تازه به نام workspace-lab ترمینال PowerShell را باز کنید. فرمان زیر یک package.json اولیه می‌سازد. npm همراه نصب معمول Node ارائه می‌شود؛ لازم نیست برای این تمرین حساب npm بسازید یا چیزی منتشر کنید. در PowerShell از npm.cmd استفاده می‌کنیم تا با انتخاب فایل npm.ps1 و محدودیت اجرای اسکریپت‌های PowerShell درگیر نشویم. این انتخاب مجوز یا سیاست امنیتی سیستم را تغییر نمی‌دهد.

npm.cmd init -y

قرارداد کوچک و قابل خواندن

package.json ساخته‌شده را در ویرایشگر با متن زیر جایگزین و ذخیره کنید. JSON توضیح //، کوتیشن تکی و ویرگول اضافه بعد از آخرین عضو را نمی‌پذیرد. نام خصوصی این تمرین به معنی نام دامنه یا نشانی وب نیست. private: true مانع انتشار تصادفی بسته با npm publish می‌شود؛ پوشه را رمزگذاری یا مخفی نمی‌کند.

{
  "name": "workspace-lab",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "engines": { "node": ">=24" },
  "scripts": {
    "start": "node app.mjs",
    "test": "node --test calc.test.mjs"
  }
}

محدودهٔ engines در این نمونه حداقل نسخه را مستند می‌کند؛ به‌طور معمول تضمین سختی برای توقف اجرا نیست. پیش از کار node --version را هم ببینید. نسخهٔ LTS پشتیبانی‌شده و به‌روز شاخهٔ ۲۴ یا ۲۶ برای این مسیر مناسب است؛ عدد حداقل در این فایل را با توصیهٔ استفاده از نسخهٔ وصله‌شده اشتباه نگیرید. type: module انتخاب فایل‌های .js همین بسته را نیز روشن می‌کند، هرچند مثال ما پسوند صریح .mjs دارد.

سه فایل زیر را کنار package.json بسازید. calc.mjs مسئول محاسبه است، app.mjs خروجی را نشان می‌دهد و calc.test.mjs انتظار ما را ثبت می‌کند. جداکردن فایل آزمون کمک می‌کند با اجرای برنامه، آزمون‌ها ناخواسته اجرا نشوند. آزمون‌ها به node:test و node:assert داخلی متکی‌اند و برایشان نصب Jest یا بستهٔ دیگری لازم نیست.

// calc.mjs
export function remaining(total, spent) {
  if (![total, spent].every(Number.isSafeInteger) || total < 0 || spent < 0) {
    throw new TypeError('Expected non-negative integer amounts');
  }
  return total - spent;
}

// app.mjs
import { remaining } from './calc.mjs';
console.log(remaining(500000, 180000)); // 320000

// calc.test.mjs
import test from 'node:test';
import assert from 'node:assert/strict';
import { remaining } from './calc.mjs';
test('reports remaining budget and overspending', () => {
  assert.equal(remaining(500000, 180000), 320000);
  assert.equal(remaining(100000, 120000), -20000);
});
test('rejects a text amount', () => {
  assert.throws(() => remaining('500000', 180000), TypeError);
});

npm.cmd start
npm.cmd test

پس از پیام‌های خود npm، فرمان start عدد 320000 را چاپ می‌کند. در test باید دو آزمون موفق و صفر شکست ببینید؛ شکل و زمان گزارش میان نسخه‌ها تغییر می‌کند. آزمون دوم مهم است، چون عددی که از فرم به شکل متن رسیده را بی‌خبر نمی‌پذیرد. هزینهٔ بیش از بودجه در این قرارداد خطا نیست و ماندهٔ منفی می‌دهد؛ این یک تصمیم محصول است که در آزمون نوشته‌ایم.

محلی، سراسری و پوستهٔ اجرای فرمان

بستهٔ محلی جزئی از پروژه و معمولاً در node_modules است؛ نصب سراسری برای در دسترس بودن بعضی ابزارهای خط فرمان در چند پوشه استفاده می‌شود. برای این درس هیچ‌کدام لازم نیست. اگر بعداً ابزار محلی داشته باشید، npm scripts مسیر اجرایی محلی آن را در اختیار فرمان می‌گذارد. برای هر خطای command not found به نصب سراسری پناه نبرید؛ ممکن است پوشهٔ اشتباه باز باشد یا نصب همان پروژه کامل نشده باشد.

ترمینال شما PowerShell است، اما npm scripts به‌طور پیش‌فرض در ویندوز با cmd.exe اجرا می‌شوند، مگر پیکربندی تغییر کرده باشد. بنابراین نوشتن $env:PORT=... در مقدار start یک قرارداد قابل‌حمل نیست. فرمان‌های این درس مستقیماً node را اجرا می‌کنند و برای کارهای پیچیده می‌توان اسکریپت جاوااسکریپت جدا ساخت. همچنین پیش از اجرای script در پروژهٔ دریافتی، متن scripts را بخوانید؛ یک نام آشنای start نمی‌گوید داخل فرمان چه عملی انجام می‌شود.

تمرین، پاسخ و رفع خطا

یک script به نام check اضافه کنید که node --check app.mjs را اجرا کند و سپس npm.cmd run check بزنید. پاسخ: مقدار check همان فرمان بالا در شیء scripts است. این بررسی نحو را کنترل می‌کند و خروجی یا درستی منطق را تضمین نمی‌کند؛ test همچنان لازم است. اگر Missing script دیدید، نام کلید و فایل ذخیره‌شده را کنترل کنید. اگر ENOENT به package.json اشاره می‌کند، با Get-Location و Get-ChildItem بررسی کنید در پوشهٔ درست هستید. برای EJSONPARSE، محل خطای JSON را اصلاح کنید، نه نصب دوبارهٔ Node.

منابع رسمی

npm، package.json: https://docs.npmjs.com/cli/v11/configuring-npm/package-json/
npm، اسکریپت‌ها و پوستهٔ اجرا: https://docs.npmjs.com/cli/v11/using-npm/scripts/
Node.js، آزمون‌نویسی: https://nodejs.org/api/test.html
Node.js، بررسی نحو با خط فرمان: https://nodejs.org/api/cli.html

تألیف و مثال‌های اختصاصی: تحریریه درس‌آوند. اجرای start و دو آزمون با Node.js 24.22.1 در لینوکس بررسی شده است؛ فرمان معادل npm.cmd در ویندوز در این محیط اجرا نشده است.