اجرای فایل و نسخه
فایل برنامه را با runtime اجرا و نسخهٔ فعال را بررسی کنید.
node app.jsnode --versionnpm --version
راهنمای APIهای اصلی Node.js برای ماژولها، فایل و مسیر، HTTP، رویداد، stream و آزمون؛ جدا از چیتشیت Express. Node.js محیط اجرای JavaScript در سمت سرور است. در یک پروژه، قرارداد CommonJS یا ES Modules را بر اساس package.json و پسوند فایل یکدست انتخاب کنید. از APIهای Promise برای I/O ناهمگام استفاده کنید و مسیرها را با APIهای path بسازید. ورودی فایل و مقدار محیطی را اعتبارسنجی کنید. از این صفحه بهعنوان مرجع سریع استفاده کنید و مثالها و نکتهها را با نسخهٔ ابزار، نیاز و شرایط واقعی پروژهٔ خود تطبیق دهید.
فایل برنامه را با runtime اجرا و نسخهٔ فعال را بررسی کنید.
node app.jsnode --versionnpm --versionماژولهای داخلی را با پیشوند node: وارد کنید.
import { readFile } from "node:fs/promises";import { join } from "node:path";const filePath = join(process.cwd(), "data.json");const contents = await readFile(filePath, "utf8");در پروژهٔ CommonJS از require و module.exports استفاده کنید.
const { readFile } = require("node:fs/promises");function loadConfig(path) { return readFile(path, "utf8");}module.exports = { loadConfig };فرمانهای تکراری پروژه را به scriptهای نامدار بسپارید.
{ "scripts": { "start": "node src/index.js", "test": "node --test" }}برای فایل کوچک، readFile متن را با encoding مشخص میخواند.
import { readFile } from "node:fs/promises";const text = await readFile("./notes.txt", "utf8");مسیر مقصد و سیاست بازنویسی را پیش از نوشتن بررسی کنید.
import { writeFile } from "node:fs/promises";await writeFile("./output.txt", "Generated locally\n", { encoding: "utf8",});بهجای چسباندن رشتهٔ مسیر، از node:path استفاده کنید.
import { join, resolve } from "node:path";const configPath = join(process.cwd(), "config", "app.json");const absolutePath = resolve(configPath);تنظیمات محیطی را در startup بررسی کنید و secret را در log چاپ نکنید.
const port = Number(process.env.PORT ?? 3000);if (!Number.isInteger(port) || port < 1 || port > 65535) { throw new Error("PORT must be a valid TCP port");}سرور سادهٔ HTTP را با ماژول داخلی node:http بسازید.
import { createServer } from "node:http";const server = createServer((request, response) => { response.writeHead(200, { "content-type": "text/plain; charset=utf-8" }); response.end("Hello from Node.js");});server.listen(3000, "127.0.0.1");خطاهای Promise را با try/catch در مرز مناسب مدیریت کنید.
async function loadData() { try { const response = await fetch("https://example.com/data"); if (!response.ok) throw new Error(`HTTP ${response.status}`); return await response.json(); } catch (error) { console.error("Unable to load data", error); throw error; }}timer را در صورت بینیازی لغو کنید تا کار پسزمینه نماند.
const timeout = setTimeout(() => { console.log("Timed out");}, 1000);clearTimeout(timeout);رویداد سفارشی را subscribe کنید و listener غیرضروری را پاک کنید.
import { EventEmitter } from "node:events";const events = new EventEmitter();const onReady = () => console.log("ready");events.once("ready", onReady);events.emit("ready");برای انتقال فایل بزرگ از stream استفاده کنید.
import { createReadStream, createWriteStream } from "node:fs";import { pipeline } from "node:stream/promises";await pipeline( createReadStream("input.log"), createWriteStream("archive.log"),);آزمونها را با test runner داخلی و assert بنویسید.
import test from "node:test";import assert from "node:assert/strict";test("adds two values", () => { assert.equal(2 + 3, 5);});فایل برنامه را با node app.js اجرا و نسخهٔ runtime را با node --version بررسی کنید.
قرارداد CommonJS و ES Modules را مطابق تنظیمات package و پسوند فایل انتخاب کنید.
برای I/O فایل از APIهای async در node:fs/promises استفاده کنید.
مسیرها را با node:path بسازید تا وابسته به separator سیستمعامل نباشند.
از متغیر محیطی برای پیکربندی محیط اجرا استفاده کنید و مقدار secret را log نکنید.
برای HTTP ساده از node:http یا برای نیازهای سطح بالاتر از framework مناسب بهره بگیرید.
درخواستهای شبکه و فایل را ناهمگام اجرا کنید و خطا و timeout را مدیریت کنید.
برای دادهٔ حجیم stream را بهجای بارگذاری کامل در حافظه بررسی کنید.
از node:test و node:assert برای آزمونهای پایهٔ داخلی استفاده کنید.
نسخهٔ Node.js و package manager پروژه را ثبت کنید تا محیط توسعه و CI همسان باشد.
APIهای Node.js ممکن است میان نسخههای LTS تفاوت داشته باشند؛ runtime هدف و نسخهٔ package manager را در پروژه ثبت کنید.
برای فایل، شبکه و پایگاه داده API ناهمگام را ترجیح دهید؛ I/O همگام در مسیر درخواست میتواند event loop را متوقف کند.