liminfoNode.js Reference
Node.js 런타임 레퍼런스
Node.js Reference 소개
Node.js 레퍼런스는 모든 백엔드 JavaScript 개발자가 매일 사용하는 Node.js 내장 모듈의 전체 표준 라이브러리를 다룹니다. 모듈 섹션은 CommonJS(require/module.exports)와 ES 모듈(import/export) 문법을 나란히 문서화하고, 크로스 플랫폼 파일 경로 처리를 위한 path 모듈, CPU 수·메모리·플랫폼 정보를 읽는 os 모듈, WHATWG URL API를 이용한 URL 파싱을 다룹니다. 이것들은 어떤 프레임워크를 쓰든 모든 Node.js 애플리케이션에서 사용되는 기본 블록입니다.
파일 시스템과 HTTP 섹션은 가장 일반적인 두 가지 I/O 범주를 다룹니다. fs/promises API는 readFile, writeFile, appendFile, readdir, stat, mkdir, rm, rename과 실시간 파일 변경 감지를 위한 비동기 이터레이터 기반 fs.watch로 문서화됩니다. HTTP 섹션은 원시 서버 구축을 위한 http.createServer, Node 18+에서 사용 가능한 네이티브 fetch API, TLS 인증서를 사용한 HTTPS 서버 설정, ws 라이브러리를 이용한 WebSocket 서버 생성을 다룹니다. 스트림은 Readable, Writable, Transform, 오류 안전 파이핑을 위한 stream/promises의 pipeline, 비동기 이터러블에서 스트림을 생성하는 Readable.from으로 문서화됩니다.
이벤트와 프로세스 섹션이 런타임 그림을 완성합니다. on, once, off, emit을 가진 EventEmitter와 이벤트 스트림 소비를 위한 비동기 events.on 이터레이터가 모두 다루어집니다. 프로세스 섹션은 환경 변수를 위한 process.env, 서브프로세스 실행을 위한 exec와 spawn을 가진 child_process, CPU 집약적 병렬 처리를 위한 worker_threads, process.on("SIGINT")를 이용한 graceful shutdown, uncaughtException 처리, 멀티코어 HTTP 서버 확장을 위한 cluster 모듈을 문서화합니다. 이 레퍼런스는 Node.js 백엔드 개발자, REST와 WebSocket 서비스를 구축하는 API 엔지니어, Node.js 스크립트로 인프라를 자동화하는 DevOps 엔지니어를 위한 것입니다.
주요 기능
- CommonJS require/module.exports와 ESM import/export 문법 나란히 보기
- 크로스 플랫폼 경로 처리를 위한 path.join, path.resolve, path.basename, path.extname
- fs/promises — readFile, writeFile, mkdir(recursive), rm, stat, 비동기 fs.watch
- http.createServer, Node 18+ 네이티브 fetch, TLS 인증서를 사용한 HTTPS 서버
- ws 라이브러리를 이용한 WebSocket 서버 — connection과 message 이벤트 처리
- 안전한 파이핑을 위한 stream/promises pipeline을 사용한 Readable·Writable·Transform 스트림
- EventEmitter on/once/off/emit과 비동기 for-await events.on 이터레이터
- CPU 병렬 처리를 위한 worker_threads와 멀티코어 확장을 위한 cluster 모듈
자주 묻는 질문
Node.js에서 CommonJS와 ES 모듈의 차이는 무엇인가요?
CommonJS는 require()로 가져오고 module.exports로 내보내며, 모듈은 동기적으로 로드됩니다. ES 모듈은 import/export 문법을 사용하고 최상위 await를 지원합니다. Node.js에서 .mjs 확장자를 가진 파일이나 package.json에 "type": "module"을 가진 패키지는 ESM을 사용합니다. CommonJS 파일은 .cjs나 기본 "type": "commonjs"로 사용합니다. 두 방식은 직접 혼용할 수 없습니다 — require()로 ESM을 가져올 수 없지만 ESM은 createRequire()를 사용해 CommonJS를 로드할 수 있습니다.
Node.js에서 파일을 비동기적으로 읽고 쓰는 방법은?
fs/promises 모듈을 사용합니다. const fs = require("fs/promises") 또는 import fs from "fs/promises"로 가져오세요. await fs.readFile("경로", "utf-8")로 파일을 문자열로 읽습니다. await fs.writeFile("경로", 내용)으로 파일에 씁니다(덮어쓰기). await fs.appendFile("경로", 내용)으로 끝에 추가합니다. ENOENT나 권한 오류를 처리하기 위해 항상 try/catch로 감싸세요.
Node.js가 단일 스레드인데 동시성을 어떻게 처리하나요?
Node.js는 libuv로 지원되는 논블로킹 이벤트 루프를 가진 단일 JavaScript 스레드를 사용하며, I/O 작업(파일 읽기, 네트워크 요청, DNS 조회)을 OS나 스레드 풀에 오프로드합니다. 이를 통해 각 연결마다 OS 스레드를 만들지 않고 수천 개의 동시 연결을 처리할 수 있습니다. CPU 집약적 작업은 이벤트 루프를 블록하므로, 무거운 연산에는 worker_threads를 사용해 JavaScript를 병렬 워커 스레드에서 실행하거나, cluster를 사용해 각자의 이벤트 루프를 가진 여러 프로세스를 포크하세요.
Node.js 스트림이란 무엇이고 언제 사용해야 하나요?
스트림은 모든 것을 한 번에 메모리에 로드하는 대신 청크 단위로 데이터를 방출하는 객체입니다. 데이터 소스에는 Readable 스트림(fs.createReadStream), 데이터 싱크에는 Writable 스트림(fs.createWriteStream), 흐름 중 데이터를 처리할 때는 Transform 스트림(압축, 암호화, 파싱)을 사용합니다. stream/promises의 pipeline 함수를 사용해 스트림을 적절한 오류 처리와 자동 정리로 연결하세요 — 어떤 스트림이든 오류가 발생하면 예외를 던지며, 누수가 발생할 수 있는 오래된 pipe() 메서드보다 안전합니다.
Node.js에서 셸 명령어를 실행하는 방법은?
짧은 명령어에서 출력 전체를 문자열로 원할 때는 child_process의 exec()를 사용합니다 — stdout과 stderr를 버퍼링하고 완료 시 콜백을 호출합니다. 오래 실행되는 프로세스나 stdout/stderr를 실시간으로 스트리밍해야 할 때는 spawn()을 사용합니다 — .stdout과 .stderr 스트림을 가진 ChildProcess를 반환합니다. CLI 스크립트에서는 이벤트 루프를 블록하는 execSync()나 spawnSync()를 사용할 수 있지만 서버에서는 사용하지 마세요.
worker_threads와 cluster 모듈의 차이는 무엇인가요?
worker_threads는 같은 프로세스 내에 추가 JavaScript 스레드를 생성하며 SharedArrayBuffer로 메모리를 공유하고 postMessage로 통신합니다. 이미지 처리, 암호화, 대용량 파일 파싱 같은 CPU 집약적 작업에 새 프로세스 오버헤드 없이 연산을 오프로드할 때 사용합니다. cluster는 Node.js 전체 프로세스를 여러 번 포크하고(CPU 코어당 하나) IPC로 통신합니다. 모든 CPU 코어를 활용하기 위해 HTTP 서버를 확장할 때 cluster를 사용하세요.
Node.js EventEmitter 패턴은 어떻게 동작하나요?
EventEmitter는 이름 있는 이벤트를 방출하는 Node.js 객체의 기반 클래스입니다. emitter.on("이벤트", 핸들러)로 지속 리스너를 등록하거나 emitter.once("이벤트", 핸들러)로 일회성 리스너를 등록합니다. emitter.off("이벤트", 핸들러)나 removeAllListeners()로 리스너를 제거합니다. emitter.emit("이벤트", ...인수)로 이벤트를 발생시키면 등록된 모든 리스너를 등록 순서대로 동기적으로 호출합니다. 비동기 for-await events.on(emitter, "이벤트")은 이벤트를 하나씩 소비하는 비동기 이터러블을 생성합니다.
Node.js에서 환경 변수를 처리하는 최선의 방법은?
process.env.변수명으로 환경 변수에 접근합니다. 로컬 개발에서는 .env 파일과 dotenv 라이브러리(require("dotenv").config())를 사용해 앱 코드 실행 전에 변수를 로드합니다. Node 20.6+에서는 dotenv 없이 --env-file=.env 커맨드라인 옵션을 사용할 수 있습니다. 소스 코드에 시크릿을 하드코딩하지 말고 .env 파일을 커밋하지 마세요. 프로덕션에서는 호스팅 플랫폼, Docker 환경 플래그, 또는 AWS Secrets Manager나 Vault 같은 시크릿 매니저를 통해 변수를 설정하세요.