Node.js 개발 환경 설정 가이드

작성자:

Node.js 개발의 첫걸음, 2026년 최신 환경 설정과 프로젝트 시작 방법을 권퓨터와 함께 완벽하게 마스터하세요.

이 가이드는 Node.js 개발을 처음 시작하는 분들을 위해 필수적인 환경 설정부터 첫 프로젝트 초기화, 그리고 모듈 시스템 이해까지 모든 과정을 상세히 다룹니다. 최신 버전 동향과 실전 팁을 통해 효율적인 개발 환경을 구축하고, 안정적인 Node.js 프로젝트를 시작할 수 있도록 돕겠습니다.

복잡하게 느껴질 수 있는 초기 설정 과정을 단계별로 따라하며, 2026년 기준으로 가장 권장되는 개발 워크플로우를 익혀보세요.

06주의사항 및 팁

07마무리

Node.js와 npm/Yarn 이해하기

Node.js와 npm/Yarn 이해하기

Node.js 개발을 시작하기 전에, 핵심 기술 스택인 Node.js 자체와 패키지 관리 도구인 npm 및 Yarn의 기본적인 개념을 명확히 이해하는 것이 중요합니다. 이들을 정확히 파악해야 효율적이고 안정적인 개발 환경을 구축할 수 있습니다.

Node.js란 무엇인가?

Node.js는 Chrome V8 JavaScript 엔진으로 빌드된 JavaScript 런타임입니다. 웹 브라우저 밖에서 JavaScript 코드를 실행할 수 있게 해주는 것이 핵심이며, 이를 통해 서버 개발, CLI 도구 개발, 데스크톱 애플리케이션 개발 등 다양한 분야에서 JavaScript를 활용할 수 있게 되었습니다.

특히, Node.js는 비동기 이벤트 기반 아키텍처를 채택하여 높은 처리량과 확장성을 제공합니다. 이는 I/O 집약적인 애플리케이션, 예를 들어 실시간 채팅 애플리케이션이나 스트리밍 서비스 등에 매우 적합합니다.

2026년 현재, Node.js는 웹 서비스 백엔드 개발 시장에서 여전히 강력한 위치를 차지하고 있으며, 마이크로서비스 아키텍처와 서버리스 환경에서도 활발히 사용되고 있습니다.

npm과 Yarn의 역할 및 차이점

Node.js 생태계에서 패키지 관리 도구는 개발 생산성을 크게 좌우합니다. 대표적으로 npm(Node Package Manager)과 Yarn이 있습니다.

npm은 Node.js 설치 시 기본적으로 포함되는 패키지 관리자로, 전 세계에서 가장 큰 소프트웨어 레지스트리를 자랑합니다. 수많은 오픈소스 라이브러리와 프레임워크를 쉽게 설치하고 관리할 수 있도록 돕습니다.

Yarn은 Facebook(現 Meta)에서 개발한 패키지 관리자로, npm의 초기 단점들을 보완하며 등장했습니다. 특히 속도, 안정성, 보안 측면에서 강점을 가졌습니다. Yarn은 패키지 설치 시 병렬 처리를 통해 속도를 향상시키고, yarn.lock 파일을 통해 의존성 버전을 엄격하게 관리하여 빌드 재현성을 높입니다.

현재 npm도 많은 개선을 거쳐 Yarn과 기능적으로 유사해졌습니다. 최신 npm 버전은 Yarn 못지않은 성능과 기능을 제공하므로, 프로젝트의 특성이나 팀의 선호도에 따라 선택하여 사용하면 됩니다.

2026년 최신 버전 동향

Node.js는 활발히 개발되고 있으며, 매년 새로운 LTS(Long Term Support) 버전이 출시됩니다. 2026년 현재 권장되는 LTS 버전은 안정성과 장기 지원을 고려하여 선택하는 것이 좋습니다. 최신 LTS 버전을 확인하려면 Node.js 공식 홈페이지를 참고하세요.

일반적으로, 새로운 프로젝트를 시작할 때는 최신 LTS 버전을 사용하는 것이 좋습니다. 이는 보안 업데이트와 버그 픽스를 장기간 받을 수 있기 때문입니다. 현재 시점(2026년 6월 1일)을 기준으로 Node.js 20.x, 22.x LTS 버전이 주로 사용되며, 최신 기능이 필요하다면 Current 버전을 고려할 수 있습니다.

Node.js 개발의 안정적인 시작을 위해 LTS 버전과 NVM 같은 버전 관리 도구는 필수입니다.

Node.js 개발 환경 설정

Node.js 개발 환경 설정

이제 본격적으로 Node.js 개발 환경을 설정해 보겠습니다. 여러 버전의 Node.js를 유연하게 관리하기 위해 NVM(Node Version Manager)을 사용하는 것이 일반적이며, 운영체제별로 설치 방법이 조금 다릅니다.

NVM을 이용한 버전 관리 (Mac/Linux)

NVM은 여러 Node.js 버전을 설치하고 쉽게 전환할 수 있도록 도와주는 유용한 도구입니다. 개발 환경에서 다양한 프로젝트가 각기 다른 Node.js 버전을 필요로 할 때 특히 빛을 발합니다.

NVM을 설치하려면 터미널을 열고 다음 명령어를 실행합니다:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

설치 후에는 터미널을 다시 시작하거나 source ~/.bashrc (Bash) 또는 source ~/.zshrc (Zsh) 명령어로 환경 변수를 업데이트해야 합니다. NVM이 제대로 설치되었는지 확인하려면 nvm --version을 입력합니다.

Chocolatey/WSL을 이용한 버전 관리 (Windows)

Windows 환경에서는 Chocolatey (패키지 관리자)를 사용하거나, WSL(Windows Subsystem for Linux)을 설치하여 Linux 환경에서 NVM을 사용하는 것을 권장합니다.

Chocolatey 설치 후, PowerShell(관리자 권한)에서 다음 명령어로 NVM for Windows를 설치할 수 있습니다:

choco install nvm

WSL을 사용한다면, 위 Mac/Linux와 동일한 NVM 설치 방법을 따를 수 있어 보다 일관된 개발 경험을 제공합니다.

Node.js 및 npm/Yarn 설치 및 버전 확인

NVM이 설치되었다면, 이제 Node.js를 설치할 차례입니다. 2026년 기준 최신 LTS 버전인 Node.js 22.x를 설치해 보겠습니다.

nvm install 22
nvm use 22

설치 및 사용 설정 후, 다음 명령어로 Node.js와 npm 버전이 올바르게 설정되었는지 확인합니다:

node -v
npm -v

Yarn을 사용하고 싶다면, npm을 통해 Yarn을 전역으로 설치할 수 있습니다:

npm install -g yarn
yarn -v

특정 프로젝트에서 다른 Node.js 버전을 사용해야 할 경우, 프로젝트 루트 디렉터리에 .nvmrc 파일을 생성하고 원하는 버전(예: 20)을 기입하면, 해당 디렉터리에서 nvm use 명령 시 자동으로 해당 버전을 사용하게 됩니다.

VS Code 설치 및 필수 확장 프로그램

최신 Node.js 개발에는 Visual Studio Code (VS Code)가 사실상 표준 IDE로 자리 잡았습니다. VS Code를 설치하고 다음 필수 확장 프로그램을 설치하여 개발 효율을 극대화하세요.

  • ESLint: JavaScript 코드의 잠재적 오류를 찾고 코딩 스타일을 강제하여 일관성 있는 코드를 작성하도록 돕습니다.
  • Prettier: 코드 포맷터로, 자동으로 코드를 깔끔하게 정돈해 줍니다. ESLint와 함께 사용하면 코드 품질을 크게 향상시킬 수 있습니다.
  • DotENV: .env 파일의 환경 변수를 하이라이팅하여 가독성을 높입니다.
  • Path Intellisense: 파일 경로 자동 완성을 제공하여 오타를 줄이고 개발 속도를 높입니다.

첫 Node.js 프로젝트 시작하기

첫 Node.js 프로젝트 시작하기

이제 개발 환경 설정이 완료되었으니, 첫 Node.js 프로젝트를 생성하고 기본적인 구조를 살펴보겠습니다. 이 과정은 모든 Node.js 프로젝트의 시작점입니다.

프로젝트 디렉토리 생성 및 초기화

새로운 프로젝트를 시작하려면 먼저 프로젝트를 위한 디렉토리를 만들고 해당 디렉토리로 이동합니다. 터미널에서 다음 명령어를 실행하세요:

mkdir my-first-nodejs-app
cd my-first-nodejs-app

이제 npm init 또는 yarn init 명령어를 사용하여 프로젝트를 초기화합니다. -y 옵션을 사용하면 모든 질문에 기본값으로 응답하여 빠르게 초기화할 수 있습니다.

npm init -y
# 또는
yarn init -y

이 명령어를 실행하면 프로젝트 루트에 package.json 파일이 생성됩니다. 이 파일은 프로젝트의 메타데이터와 의존성 정보를 담고 있습니다.

package.json 파일 이해하기

package.json 파일은 Node.js 프로젝트의 심장과 같습니다. 주요 필드들은 다음과 같습니다:

  • name: 프로젝트 이름 (소문자, 하이픈으로 구분)
  • version: 프로젝트 버전 (Semantic Versioning 규칙 준수)
  • description: 프로젝트 설명
  • main: 프로젝트의 진입점 파일 (예: index.js)
  • scripts: 자주 사용하는 명령어를 정의하는 곳 (예: "start": "node index.js")
  • keywords: 프로젝트를 설명하는 키워드 배열
  • author: 개발자 정보
  • license: 프로젝트 라이선스
  • dependencies: 프로젝트 운영에 필수적인 의존성 패키지
  • devDependencies: 개발 및 테스트에 필요한 의존성 패키지

이 파일은 프로젝트의 모든 중요한 설정을 담고 있으므로, 변경 사항을 커밋할 때 항상 포함시켜야 합니다.

간단한 Express.js 서버 구축 예시

이제 Express.js 프레임워크를 사용하여 간단한 웹 서버를 구축해 보겠습니다. Express.js는 Node.js의 가장 인기 있는 웹 프레임워크 중 하나입니다.

먼저 Express.js를 설치합니다:

npm install express
# 또는
yarn add express

다음으로, index.js 파일을 생성하고 아래 코드를 작성합니다:

// index.js
const express = require('express');
const app = express();
const port = 3000;

app.get('/', (req, res) => {
  res.send('Hello from Kwonputer Node.js App!');
});

app.listen(port, () => {
  console.log(`Server listening at http://localhost:${port}`);
});

이제 터미널에서 다음 명령어로 서버를 실행합니다:

node index.js

웹 브라우저에서 http://localhost:3000에 접속하면 “Hello from Kwonputer Node.js App!” 메시지를 볼 수 있습니다.

의존성 관리 및 스크립트

의존성 관리 및 스크립트

Node.js 프로젝트에서는 수많은 외부 라이브러리(의존성)를 사용하게 됩니다. 이들을 효율적으로 관리하고, 반복적인 작업을 자동화하는 스크립트 활용법을 알아보겠습니다.

패키지 설치 및 제거

새로운 패키지를 설치할 때는 npm install <package_name> 또는 yarn add <package_name> 명령어를 사용합니다. 예를 들어, 환경 변수 관리를 위한 dotenv 패키지를 설치하려면:

npm install dotenv
# 또는
yarn add dotenv

패키지를 제거할 때는 npm uninstall <package_name> 또는 yarn remove <package_name>를 사용합니다.

npm uninstall dotenv
# 또는
yarn remove dotenv

패키지를 설치하면 node_modules 디렉터리에 실제 파일이 다운로드되고, package.json의 dependencies 또는 devDependencies 필드에 추가됩니다.

devDependencies와 dependencies

패키지는 크게 두 가지 유형으로 분류됩니다:

  • dependencies: 애플리케이션이 실제로 동작하는 데 필요한 패키지입니다. 예를 들어, Express.js와 같은 웹 프레임워크나 데이터베이스 드라이버 등이 여기에 해당합니다. npm install <package> 또는 yarn add <package>로 설치됩니다.
  • devDependencies: 개발 및 테스트 과정에서만 필요하고, 실제 배포된 애플리케이션에서는 필요 없는 패키지입니다. 예를 들어, Babel(트랜스파일러), Webpack(번들러), Jest(테스트 프레임워크), Nodemon(개발 서버 자동 재시작) 등이 여기에 해당합니다. npm install <package> --save-dev 또는 yarn add <package> --dev로 설치됩니다.

이 두 가지를 명확히 구분하여 관리하는 것은 배포 시 애플리케이션의 크기를 줄이고, 불필요한 의존성을 제거하여 효율성을 높이는 데 중요합니다.

package.json 스크립트 활용

package.json의 scripts 필드는 반복적인 작업을 자동화하는 데 매우 유용합니다. 앞서 만든 Express.js 서버를 실행하는 스크립트를 추가해 보겠습니다.

package.json 파일에 다음 내용을 추가합니다:

  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },

이제 npm start 또는 yarn start 명령어로 서버를 실행할 수 있습니다. dev 스크립트는 nodemon을 사용하여 코드 변경 시 서버를 자동으로 재시작합니다. nodemon은 개발 의존성이므로 npm install nodemon --save-dev로 설치해야 합니다.

모듈 시스템 이해하기 (CommonJS vs ES Modules)

모듈 시스템 이해하기 (CommonJS vs ES Modules)

JavaScript에는 모듈을 불러오고 내보내는 두 가지 주요 시스템이 있습니다: CommonJS와 ES Modules(ESM). Node.js는 오랫동안 CommonJS를 사용해왔지만, 최근에는 ES Modules로의 전환이 활발히 이루어지고 있습니다.

require/module.exports (CommonJS)

CommonJS는 Node.js가 초기에 채택한 모듈 시스템입니다. require() 함수를 사용하여 모듈을 불러오고, module.exports 또는 exports 객체를 통해 모듈을 내보냅니다.

모듈 내보내기 (CommonJS):

// math.js
function add(a, b) {
  return a + b;
}
module.exports = { add };

모듈 불러오기 (CommonJS):

// app.js
const math = require('./math');
console.log(math.add(5, 3)); // 8

CommonJS는 동기적으로 모듈을 로드하며, 주로 Node.js 환경에서 사용되어 왔습니다.