next dev 포트 변경하는 5가지 방법

Introduction

Next.js 개발 서버는 기본적으로 포트 3000을 사용합니다. 여러 프로젝트를 동시에 작업하거나 포트 충돌이 발생할 때 포트를 변경해야 합니다. 이 글에서는 포트를 변경하는 다양한 방법을 다룹니다.

Environment

# 프로젝트 구조
my-app/
├── package.json
├── next.config.js
├── .env.local
└── app/
    └── page.tsx

# 기술 스택
Next.js: 14.2.5
Node.js: 18.17.0

Problem

기본 포트 3000이 이미 사용 중인 경우 에러가 발생합니다:

$ npm run dev

ready - started server on 0.0.0.0:3000, url: http://localhost:3000
Error: listen EADDRINUSE: address already in use :::3000

Analysis

Next.js 포트 변경은 여러 레벨에서 가능합니다:

1. CLI 옵션 (-p 플래그)
2. 환경 변수 (PORT)
3. package.json 스크립트
4. next.config.js 설정
5. 자동 포트 할당

Solution

1. CLI 플래그 사용

# 가장 간단한 방법: -p 플래그
next dev -p 3001

# 특정 호스트 바인딩
next dev -p 3001 -H 127.0.0.1

# 포트 범위 지정 (3000-3010 중 사용 가능한 포트)
next dev -p 3000:3010

2. 환경 변수 설정

# .env.local
PORT=3001

# 또는 터미널에서 직접 설정
PORT=3001 npm run dev

# Windows
$env:PORT=3001; npm run dev

3. package.json 스크립트

{
  "scripts": {
    "dev": "next dev",
    "dev:3001": "next dev -p 3001",
    "dev:3002": "next dev -p 3002",
    "dev:alt": "next dev -p 8080"
  }
}

# 사용법
npm run dev:3001
npm run dev:alt

4. next.config.js 설정

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // 개발 서버 설정
  devIndicators: {
    buildActivityPosition: 'bottom-right',
  },
};

module.exports = nextConfig;

5. 자동 포트 할당

# Next.js 14+에서 자동으로 사용 가능한 포트 할당
next dev -p 3000:3010
# 3000이 사용 중이면 3001, 3002... 순으로 시도

// 자동 포트 할당 로직 구현
const getAvailablePort = async (startPort, endPort) => {
  const net = require('net');
  
  for (let port = startPort; port <= endPort; port++) {
    const isAvailable = await new Promise((resolve) => {
      const server = net.createServer();
      server.listen(port, () => {
        server.close(() => resolve(true));
      });
      server.on('error', () => resolve(false));
    });
    
    if (isAvailable) {
      return port;
    }
  }
  
  throw new Error(`No available port in range ${startPort}-${endPort}`);
};

// 사용 예시
getAvailablePort(3000, 3010).then(port => {
  console.log(`Available port: ${port}`);
});

6. Docker 환경에서의 포트 설정

# Dockerfile
FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .

# 환경 변수로 포트 설정
ENV PORT=3000

EXPOSE ${PORT}

CMD ["npm", "run", "dev"]

# docker-compose.yml
version: '3.8'

services:
  app:
    build: .
    ports:
      - "3001:3000"  # 호스트 3001 -> 컨테이너 3000
    environment:
      - PORT=3000

7. VS Code launch.json 설정

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: start server",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "env": {
        "PORT": "3001"
      }
    }
  ]
}

Lessons Learned

1. CLI 플래그 우선: -p 플래그가 가장 빠르고 명시적
2. 환경 변수 활용: 프로젝트별로 다른 포트 사용 시 환경 변수 추천
3. 자동 할당 활용: 포트 충돌 방지를 위해 자동 할당 기능 활용
4. Docker 주의: 컨테이너 내부 포트와 호스트 포트 구분

This blog does not accept any external sponsorships, affiliate marketing, or ad revenue.