본문으로 건너뛰기
AIDevOps
  • Learn
  • Learning Paths
  • Practice
  • Open Source
  • Books
  • Engineering

    AI DevOpsAI 서비스 개발·운영 전체 지도LLMOpsLLM 배포·평가·관측실전 프로젝트AI Agent 프로젝트 실습

    Knowledge

    Docs기술 문서 모음Blog엔지니어링 아티클Plogger개발 기록 피드

    Validate

    Certification3단계 역량 인증 · 준비 중
AI Models
LlamaMistralGemmaDeepSeekQwen
⚙️ Backend
Backend 입문 & 로드맵Python 기본FastAPIDjangoFlask|CGoGinNode.js
🤖 AI 실전 개발
AI 실전 입문 & 로드맵Hugging FaceLangChainLlamaIndexLLMOps|LangGraphMCPMulti-AgentAgent Evaluation
🧠 AI Core
AI 입문 & 로드맵ML FundamentalsLLM Fundamentals|Python AIC++|PyTorchTensorFlowJAX
🧠 AI Agent 개발
금융 AI AgentLLM API 서버주식 투자 AgentAIOps AI Agent교육 AI Agent코딩 AI Agent
🌱 Spring Cloud
Spring 입문 & 로드맵Spring Cloud GatewaySpring BootJava|Spring AISpring SecuritySpring BatchSpring JPA
🐳 DevOps
DevOps 입문 & 로드맵LinuxDockerCI/CD|Kubernetes 기본K8s 심화/실무PrometheusGrafana
🧱 인프라
인프라 입문 & 로드맵NginxRedis
☁️ 클라우드
클라우드 입문 & 로드맵AWSGCPAzureNCPCloudflare
🎨 Frontend
Frontend 입문 & 로드맵JavaScriptTypeScript|ReactNext.js|VueNuxt
📱 Mobile
Mobile 입문 & 로드맵KotlinAndroidFlutter
💾 Database
DB 입문 & 로드맵공통 SQLOracleMySQLPostgreSQL|MongoDB벡터 DB
🧪 검증
k6JMeternGrinder
AIDevOps

Engineering AI. From Code to Production.
AI와 AI Agent를 개발하고 운영하기 위한 엔지니어링 학습 플랫폼

Learn

  • 전체 가이드
  • Learning Paths
  • Practice
  • Books

Resources

  • AI DevOps
  • LLMOps
  • 실전 프로젝트
  • Docs
  • Blog
  • Plogger
  • Open Source
  • Certification (준비 중)

Start Here

  • AI Core 로드맵
  • AI 실전 개발 로드맵
  • Spring Cloud 로드맵
  • DevOps 로드맵
  • 인프라 로드맵

 

  • 클라우드 로드맵
  • Frontend 로드맵
  • Mobile 로드맵
  • Backend 로드맵
  • Database 로드맵
© 2026 AI DevOps Korea. All rights reserved.
이용약관개인정보처리방침Sitemaptestforge.kr
  1. Home
  2. Learn
  3. Backend
  4. Node.js
JavaScript 런타임 가이드

🟢 Node.js 완전 가이드

Visitors

JavaScript를 서버에서 실행하는 Node.js. npm 생태계, 이벤트 루프, 파일 시스템, HTTP 서버, Express.js까지 한국어로 배우세요.

  • Intermediate · 중급
  • 업데이트 2026.09.19
  • 약 6분 읽기
  • 9개 섹션
  • 예제 코드 6개
  • 웹 IDE 실습 제공
🟢

Node.js 웹 IDE

설치 없이 브라우저에서 코드를 실행하고 단계별 예제로 익혀보세요.

웹 IDE 열기 →
Express.js API이벤트 루프npm 생태계CLI 도구

목차

0 / 11
  1. 가이드 사용법
  2. 구조 다이어그램
  3. Node.js란?
  4. npm & package.json
  5. ES Modules vs CommonJS
  6. 이벤트 루프 & 비동기
  7. 파일 시스템 (fs)
  8. Express.js
  9. Node.js 설계
  10. 운영 기준
  11. 검증 전략
목차 11개 섹션
  1. 가이드 사용법
  2. 구조 다이어그램
  3. Node.js란?
  4. npm & package.json
  5. ES Modules vs CommonJS
  6. 이벤트 루프 & 비동기
  7. 파일 시스템 (fs)
  8. Express.js
  9. Node.js 설계
  10. 운영 기준
  11. 검증 전략

가이드 사용법

읽는 방향

Node.js를 실무 흐름으로 이해하기

JavaScript를 서버에서 실행하는 Node.js. npm 생태계, 이벤트 루프, 파일 시스템, HTTP 서버, Express.js까지 한국어로 배우세요. 이 가이드는 개념을 나열하기보다, 실제 프로젝트에서 판단해야 하는 순서대로 내용을 따라갈 수 있게 구성했습니다.

핵심 관점

프론트엔드 / 앱 개발

화면을 그리는 법에서 멈추지 않고, 상태, 데이터 요청, 라우팅, 접근성, 배포 단위까지 함께 봅니다.

Express.js API이벤트 루프npm 생태계CLI 도구

구조 다이어그램

글로 읽은 내용을 머릿속에 오래 남기려면 먼저 흐름을 그림으로 잡는 편이 좋습니다. 아래 두 그림은 Node.js를 학습할 때 계속 되돌아볼 수 있는 기준 지도입니다.

학습 흐름

다이어그램 렌더링 중…

아키텍처 관점

다이어그램 렌더링 중…

Node.js란?

Node.js를 처음 펼칠 때는 세부 명령보다 큰 그림이 먼저입니다. 이 섹션에서는 앞으로 배울 개념들이 어떤 문제를 풀기 위해 등장했는지부터 잡아봅니다.

Node.js는 Chrome V8 엔진으로 JavaScript를 서버에서 실행하는 런타임입니다. 이벤트 루프 기반 논블로킹 I/O로 높은 동시성을 처리합니다.
BASH
# nvm으로 버전 관리
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 22
nvm use 22
node --version  # v22.x.x

npm & package.json

여기서는 npm & package.json을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

package.json은 프로젝트의 이름·버전·의존성·실행 스크립트를 정의하는 명세 파일입니다. `npm install`은 package.json의 버전 범위 안에서 최신 버전을 설치하지만, `npm ci`는 package-lock.json에 고정된 버전을 정확히 그대로 설치합니다 — CI 환경에서는 재현성을 위해 항상 npm ci를 사용하세요.
package.jsonJSON
{
  "name": "my-app",
  "version": "1.0.0",
  "scripts": {
    "dev": "node --watch src/index.js",
    "build": "tsc",
    "test": "node --test"
  },
  "dependencies": {
    "express": "^4.19.0"
  },
  "devDependencies": {
    "typescript": "^5.5.0"
  }
}
명령동작
npm installpackage.json 버전 범위 내에서 설치, lock 파일 갱신 가능
npm cilock 파일에 고정된 버전 그대로 설치 — 빠르고 재현 가능, CI에서 표준
^1.2.31.x.x 범위 내 최신 버전 허용 (semver 마이너/패치 업데이트)
~1.2.31.2.x 범위 내 최신 버전만 허용 (패치 업데이트만)

Tip

package-lock.json은 반드시 git에 커밋하세요 — 팀원마다, 또는 로컬과 CI마다 설치되는 의존성 버전이 미묘하게 달라지는 문제를 막아줍니다.

ES Modules vs CommonJS

여기서는 ES Modules vs CommonJS을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

package.json에 "type": "module"을 선언하면 그 프로젝트의 .js 파일은 모두 import/export 문법을 쓰는 ES Modules로 해석됩니다. 이 선언이 없으면 Node는 기존 방식인 CommonJS(require/module.exports)로 동작하므로, 두 방식을 섞어 쓰면 확장자(.mjs/.cjs)나 설정으로 명확히 구분해줘야 합니다.
package.jsonJAVASCRIPT
// ES Modules 사용 선언
{ "type": "module" }

// ESM
import fs from 'node:fs/promises';
export const helper = () => {};

// CJS (기본값, type:module 없을 때)
const fs = require('fs');
module.exports = { helper };

이벤트 루프 & 비동기

여기서는 이벤트 루프 & 비동기을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

Node.js는 단일 스레드에서 동작하지만, I/O 작업(파일 읽기, 네트워크 요청, 타이머)을 libuv에 위임하고 그 결과를 이벤트 루프가 콜백 큐에서 꺼내 처리하는 방식으로 논블로킹 동시성을 구현합니다. 즉 "여러 작업을 동시에 실행"하는 게 아니라 "기다리는 동안 다른 작업을 먼저 처리"하는 구조입니다.
다이어그램 렌더링 중…
order.jsJAVASCRIPT
console.log("1. 동기 코드");

setTimeout(() => console.log("4. setTimeout (매크로태스크)"), 0);

Promise.resolve().then(() => console.log("3. Promise.then (마이크로태스크)"));

console.log("2. 동기 코드");

// 출력 순서: 1 → 2 → 3 → 4
// 마이크로태스크(Promise)는 현재 동기 코드가 끝나자마자,
// 매크로태스크(setTimeout)보다 항상 먼저 처리됩니다.

Tip

CPU를 많이 쓰는 무거운 동기 연산(예: 큰 배열 정렬)을 메인 스레드에서 실행하면 그동안 이벤트 루프 전체가 멈춰 다른 모든 요청이 지연됩니다 — worker_threads나 별도 프로세스로 분리하세요.

파일 시스템 (fs)

여기서는 파일 시스템 (fs)을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

콜백 기반의 오래된 `fs` API 대신, 최신 코드에서는 async/await와 자연스럽게 어울리는 `fs/promises`를 기본으로 사용합니다. 대용량 파일은 전체를 메모리에 올리는 대신 스트림으로 조금씩 읽고 쓰는 편이 메모리 사용량 면에서 안전합니다.
files.jsJAVASCRIPT
import { readFile, writeFile } from 'node:fs/promises';
import { createReadStream, createWriteStream } from 'node:fs';

// 작은 파일 — 전체를 메모리에 올려도 무방
const data = await readFile('config.json', 'utf8');
await writeFile('output.json', JSON.stringify(JSON.parse(data), null, 2));

// 큰 파일 — 스트림으로 조금씩 처리 (메모리에 전체를 올리지 않음)
createReadStream('large-input.csv')
  .pipe(createWriteStream('large-output.csv'));

Tip

수백 MB 이상의 파일을 readFile로 통째로 읽으면 메모리 사용량이 파일 크기만큼 치솟습니다 — 로그 처리, 파일 변환처럼 순차 처리가 가능한 작업은 스트림을 우선 고려하세요.

Express.js

여기서는 Express.js을 실제 코드와 함께 확인합니다. 예제를 그대로 따라 하기보다, 입력과 출력, 그리고 바뀌기 쉬운 부분이 어디인지 보면서 읽어보세요.

Express는 미들웨어를 순서대로 쌓아 요청을 처리하는 구조로, app.use(express.json())처럼 등록한 미들웨어가 그 뒤에 오는 모든 라우트에 적용됩니다. 매개변수가 4개(err, req, res, next)인 함수는 Express가 자동으로 에러 핸들러로 인식하므로, 라우트에서 발생한 예외를 next(err)로 넘기면 이 핸들러 하나로 모아서 처리할 수 있습니다.
app.jsJAVASCRIPT
import express from 'express';
import cors from 'cors';

const app = express();
app.use(cors());
app.use(express.json());

app.get('/users', async (req, res) => {
    const users = await db.findAll();
    res.json(users);
});

app.use((err, req, res, next) => {
    console.error(err);
    res.status(500).json({ error: err.message });
});

app.listen(3000, () => console.log('Server on :3000'));

Node.js 실무 설계

Node.js 실무 설계은 선택지가 갈리는 지점입니다. 표를 기준으로 각 방법의 쓰임새와 운영상의 차이를 비교해두면 이후 판단이 훨씬 쉬워집니다.

Node.js는 event loop를 막지 않는 구조가 핵심입니다. CPU 작업, I/O 작업, background job을 분리하고 module boundary를 명확히 해야 합니다.
결정 지점확인 질문실무 기준
경계Node.js 코드에서 바뀌기 쉬운 부분은 어디인가?입출력, 설정, 외부 연동, 핵심 규칙을 분리합니다.
상태상태가 어디서 생성되고 어디서 사라지는가?상태 소유자와 수명 주기를 코드로 드러냅니다.
장애실패했을 때 호출자는 무엇을 받는가?timeout, fallback, error contract를 먼저 정합니다.

Node.js 운영 기준

이 섹션은 Node.js 운영 기준을 실무 관점에서 정리합니다. 개념을 외우기보다, 어떤 상황에서 이 기준을 꺼내 쓸지에 초점을 맞춰보세요.

운영에서는 event loop delay, memory leak, unhandled rejection, connection reuse, graceful shutdown을 봐야 합니다.

Tip

  • event loop delay
  • graceful shutdown
  • unhandled rejection
  • contract tests

Node.js 검증 전략

Node.js 검증 전략은 선택지가 갈리는 지점입니다. 표를 기준으로 각 방법의 쓰임새와 운영상의 차이를 비교해두면 이후 판단이 훨씬 쉬워집니다.

API contract, async error handling, fake timers, integration test를 포함해야 합니다.
품질 축검증 방법완료 기준
정확성정상/실패 케이스를 자동화합니다.핵심 시나리오가 재현 가능하게 통과합니다.
회귀 방지버그 수정 시 동일 케이스를 테스트로 남깁니다.같은 장애가 다시 배포되지 않습니다.
운영성로그, 메트릭, 알림을 확인합니다.문제가 생겼을 때 원인 추적 경로가 있습니다.
← 이전 가이드Gin