How to optimize your local development environment

김동현·2026년 3월 5일
docsnext.js

next.js 공식문서 번역

목록 보기
51/79

title: 로컬 개발 환경 최적화하는 방법 (How to optimize your local development environment)
description: Next.js로 로컬 개발 환경을 어떻게 최적화하는지 배워보세요.
url: "https://nextjs.org/docs/app/guides/local-development"
version: 16.1.6
lastUpdated: 2026-02-27
prerequisites:

안녕하세요 여러분! 멘토입니다. 오늘은 Next.js 공식 문서를 함께 살펴보면서, 여러분의 로컬 개발 환경을 어떻게 하면 더 빠르고 쾌적하게 만들 수 있는지 알아볼 거예요.

Next.js는 기본적으로 개발자 경험(DX)을 정말 중요하게 생각하고 설계되었어요. 하지만 여러분이 만드는 애플리케이션의 규모가 점점 커지다 보면, 로컬에서 개발할 때 컴파일 시간이 점점 느려지는 걸 느끼실 수 있을 거예요. 이 문서에서는 이런 흔한 컴파일 타임 성능 문제들을 어떻게 찾아내고 해결할 수 있는지 가이드해 줍니다. 제가 실무를 하면서 겪었던 팁들도 팍팍 넣어드릴 테니 끝까지 잘 따라와 주세요!

로컬 개발(Local dev) vs. 프로덕션(Production)

가장 먼저 이해해야 할 건 next dev로 실행하는 개발 환경과, next build 및 next start로 실행하는 프로덕션(실제 서비스) 환경의 차이점이에요.

next dev 환경에서는 여러분이 애플리케이션의 특정 라우트(페이지)를 열거나 이동할 때, 그 순간에 해당 라우트만 컴파일을 진행해요. 이걸 'On-demand 컴파일' 또는 'Lazy 컴파일'이라고 부르기도 하는데요. 덕분에 전체 애플리케이션이 다 컴파일될 때까지 기다릴 필요 없이 개발 서버를 아주 빠르게 띄울 수 있고, 메모리 사용량도 훨씬 적죠.

반면에 프로덕션 빌드(next build)를 실행하면 파일 용량을 줄이는 압축(Minifying) 작업이나 캐싱을 위한 콘텐츠 해시 생성 같은 다른 최적화 작업들이 전부 적용돼요. 이런 작업들은 로컬에서 개발할 때는 굳이 필요하지 않으니까 로컬에선 생략되는 거죠.

로컬 개발 성능 향상시키기 (Improving local dev performance)

자, 본격적으로 로컬 환경을 빠르게 만드는 8가지 방법을 알아볼까요?

1. 컴퓨터의 백신 프로그램(Antivirus) 확인하기

가장 의외일 수 있지만, 백신 소프트웨어가 파일 접근 속도를 엄청나게 떨어뜨릴 수 있어요! 보통 Windows 환경에서 더 자주 발생하지만, 백신이 설치된 어떤 시스템이든 문제가 될 수 있죠. 파일이 변경될 때마다 백신이 검사하려 들면 컴파일이 느려지거든요.

Windows를 사용하신다면, 여러분의 프로젝트 폴더를 Microsoft Defender 백신 제외 목록에 추가할 수 있어요.

  1. "Windows 보안(Windows Security)" 앱을 열고, "바이러스 및 위협 방지" → "설정 관리" → "제외 추가 또는 제거"를 선택하세요.
  2. "폴더" 제외를 추가하고, 여러분의 프로젝트 폴더를 선택하시면 됩니다.

macOS를 사용하신다면, 터미널 내부에서 Gatekeeper를 비활성화할 수 있어요.

  1. 터미널에서 sudo spctl developer-mode enable-terminal 명령어를 실행하세요.
  2. "시스템 설정(System Settings)" 앱을 열고 "개인정보 보호 및 보안(Privacy & Security)" → "개발자 도구(Developer Tools)"를 선택하세요.
  3. 사용 중인 터미널이 목록에 있고 활성화되어 있는지 확인하세요. 만약 iTerm이나 Ghostty 같은 서드파티 터미널을 쓰고 계신다면, 그 앱들도 목록에 추가해 주셔야 해요.
  4. 터미널을 재시작합니다.

macOS 시스템 설정의 개인정보 보호 및 보안 창 스크린샷

macOS 시스템 설정의 개발자 도구 옵션 스크린샷

만약 여러분이나 회사에서 다른 백신 솔루션(예: 알약, V3, CrowdStrike 등)을 사용 중이라면, 해당 제품의 설정에 들어가서 프로젝트 폴더를 예외 처리(검사 제외)해 주셔야 합니다.

💡 강사의 팁: 실무에 가면 회사 보안 프로그램 때문에 빌드 속도가 2~3배 느려지는 경우가 허다합니다. 개발팀장님께 요청해서 보안팀에 꼭 개발 폴더 예외 처리를 건의해 보세요!

2. Next.js 업데이트 및 터보팩(Turbopack) 사용하기

Next.js는 항상 최신 버전을 사용하는 게 좋습니다. 새 버전이 나올 때마다 성능 개선 사항이 포함되어 있거든요.

그리고 Turbopack(터보팩)은 이제 Next.js 개발 환경의 기본 번들러입니다! 기존에 쓰던 Webpack에 비해 엄청나게 빠른 성능 향상을 보여주죠. (터보팩은 Rust라는 언어로 만들어져서 기존 JavaScript 기반 번들러들보다 근본적으로 빠릅니다.)

pnpm add next@latest
pnpm dev  # Turbopack이 기본적으로 사용됩니다
npm install next@latest
npm run dev  # Turbopack이 기본적으로 사용됩니다
yarn add next@latest
yarn dev  # Turbopack이 기본적으로 사용됩니다
bun add next@latest
bun dev  # Turbopack이 기본적으로 사용됩니다

만약 프로젝트 사정상 터보팩 대신 기존의 Webpack을 계속 사용해야 한다면, 아래처럼 옵션을 줘서 실행할 수 있어요.

pnpm dev --webpack
npm run dev -- --webpack
yarn dev --webpack
bun run dev --webpack

터보팩에 대해 더 자세히 알고 싶다면 터보팩 관련 블로그 글(Learn more about Turbopack)을 읽어보세요. 버전을 올릴 때 참고할 만한 정보는 업그레이드 가이드와 codemod 문서를 확인하시면 됩니다.

3. Import 방식 점검하기 (Check your imports)

코드에서 모듈을 import하는 방식이 컴파일과 번들링 시간에 엄청난 영향을 미친다는 사실, 알고 계셨나요? 더 자세한 내용은 패키지 번들링 최적화 가이드에서 배우실 수 있고, Dependency Cruiser나 Madge 같은 의존성 분석 도구를 사용해 보는 것도 추천해요.

아이콘 라이브러리 (Icon libraries)

@material-ui/icons, @phosphor-icons/react, 혹은 react-icons 같은 라이브러리들은 우리가 딱 몇 개의 아이콘만 쓰려고 해도 수천 개의 아이콘 전체를 불러와 버릴 수 있어요. 그러니 필요한 아이콘만 콕 집어서 import 하도록 신경 써주세요.

// ❌ 이렇게 하지 마시고:
import { TriangleIcon } from '@phosphor-icons/react'

// ✅ 이렇게 하세요:
import { TriangleIcon } from '@phosphor-icons/react/dist/csr/Triangle'

어떤 import 패턴을 써야 하는지는 보통 사용하시는 아이콘 라이브러리 공식 문서에 잘 나와 있어요. 위 예시는 @phosphor-icons/react의 권장 사항을 따른 거예요.

특히 react-icons 같은 라이브러리는 안에 정말 다양한 아이콘 세트가 통째로 들어있어요. 그러니 여러 세트를 섞어 쓰기보다는 한 가지 세트만 정해서 그것만 쓰는 것이 좋습니다.

예를 들어, react-icons를 쓰는데 아래 아이콘들을 짬뽕해서 다 불러온다고 생각해 보세요.

  • pi (Phosphor Icons)
  • md (Material Design Icons)
  • tb (tabler-icons)
  • cg (cssgg)

이렇게 쓰시면, 여러분은 아이콘을 각각 딱 하나씩만 썼더라도, 컴파일러 입장에서는 수만 개의 모듈을 처리해야 하는 상황에 빠지게 됩니다. 빌드가 엄청 느려지겠죠?

배럴 파일 (Barrel files)

"배럴 파일(Barrel files)"은 여러 다른 파일에서 가져온 항목들을 한 곳에 모아서 다시 export 해주는 파일(보통 index.js나 index.ts)을 말해요. 이 배럴 파일은 빌드 속도를 늦추는 주범이 될 수 있어요. 왜냐하면 컴파일러가 이 import를 통해 모듈 스코프에 부수 효과(side-effects)가 있는지 파악하기 위해 배럴 파일에 연결된 모든 파일을 다 분석해야 하거든요.

가능하다면 배럴 파일을 거치지 말고, 특정 파일에서 직접 import 하는 습관을 들이세요. 배럴 파일과 Next.js의 내장 최적화 기능에 대해 더 알아보기를 읽어보시면 깊은 이해에 도움이 될 거예요.

💡 강사의 팁: import { Button, Input, Modal } from '@/components' 처럼 멋지게 한 줄로 쓰려고 components/index.ts를 만드시는 분들 많죠? 개발할 땐 편하지만 프로젝트가 커지면 빌드 성능을 깎아먹습니다. 조심하셔야 해요!

패키지 import 최적화 (Optimize package imports)

Next.js는 특정 패키지들의 import를 자동으로 최적화해 주는 기능이 있어요. 만약 배럴 파일을 떡칠(?)한 무거운 패키지를 사용 중이라면, next.config.js 파일에 아래처럼 추가해 보세요.

module.exports = {
  experimental: {
    optimizePackageImports: ['package-name'],
  },
}

참고로, 터보팩(Turbopack)을 쓰시면 알아서 import를 분석하고 최적화하기 때문에 이 설정이 따로 필요 없습니다. 터보팩 최고죠?

4. Tailwind CSS 설정 점검하기

요즘 Tailwind CSS 많이들 쓰시죠? Tailwind를 쓸 때는 설정이 제대로 되어있는지 확인하는 게 필수입니다.

가장 흔하게 하는 실수가 tailwind.config.js 파일의 content 배열에 node_modules 폴더나, 스캔할 필요가 전혀 없는 거대한 폴더들을 통째로 포함시키는 거예요. 이러면 Tailwind가 클래스명을 찾으려고 수만 개의 파일을 다 뒤지느라 뻗어버릴 수 있습니다.

Tailwind CSS 버전 3.4.8 이상을 쓰시면, 빌드를 느리게 만들 것 같은 설정이 있을 때 경고(warning)를 띄워줍니다.

  1. tailwind.config.js에서 스캔할 파일을 구체적으로 지정하세요:

    module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}', // ✅ 좋은 설정
    
    // ❌ 이건 범위가 너무 넓습니다.
    // `packages/**/node_modules` 폴더까지 다 스캔해 버릴 수 있어요.
    // '../../packages/**/*.{js,ts,jsx,tsx}',
  ],
}

  2. 불필요한 파일을 스캔하지 않도록 범위를 좁히세요:

    module.exports = {
  content: [
    // ✅ 더 좋은 설정 - 'src' 폴더 내부만 딱 스캔하도록 지정합니다.
    '../../packages/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
}

5. 커스텀 Webpack 설정 점검하기

만약 next.config.js에 여러분만의 커스텀 webpack 설정을 추가해 두셨다면, 그것 때문에 컴파일이 느려지고 있을 확률이 있습니다.

로컬 개발 환경에서 이 커스텀 설정들이 정말로 필요한 것인지 한번 고민해 보세요. 프로덕션 빌드할 때만 특정 도구들이 실행되도록 분기 처리를 하거나, 기본으로 제공되는 터보팩을 사용하면서 터보팩용 로더(loaders) 설정을 활용하는 방안을 찾아보세요.

6. 메모리 사용량 최적화 (Optimize memory usage)

여러분이 만드는 앱의 규모가 매우 크다면, Next.js가 기본적으로 쓰는 메모리보다 더 많은 메모리 할당이 필요할 수 있어요. 그럴 땐 메모리 사용량 최적화 가이드를 참고해서 Node.js의 메모리 제한을 늘려주세요.

7. 서버 컴포넌트(Server Components)와 데이터 패칭

로컬에서 개발하다가 서버 컴포넌트 코드를 수정하면, 새로운 변경 사항을 화면에 보여주기 위해 해당 페이지 전체가 로컬에서 다시 렌더링(re-render) 됩니다. 이때 컴포넌트 안에서 데이터를 가져오는(fetch) 로직이 있다면 그 요청도 다시 실행되죠.

이럴 때 Next.js의 실험적 기능인 serverComponentsHmrCache 옵션을 사용해 보세요. 이 옵션을 켜면, 로컬 개발 중 HMR(Hot Module Replacement - 코드 수정 시 새로고침 없이 화면만 갱신되는 기능)이 발생할 때 서버 컴포넌트의 fetch 응답을 캐싱해 줍니다. 결과적으로 화면 갱신이 훨씬 빨라지고, API 호출 비용(유료 API를 쓰는 경우)도 아낄 수 있습니다.

자세한 내용은 이 실험적 옵션에 대한 문서를 읽어보세요.

💡 부연 설명: HMR은 개발 중에 정말 중요한 기능이에요. 코드를 저장하자마자 브라우저 새로고침 없이 수정한 부분만 싹 바뀌는 마법 같은 기능이죠. 하지만 서버 컴포넌트는 서버에서 실행되다 보니 데이터를 새로 가져와야 하는 부담이 있었는데, 이 옵션이 그걸 덜어주는 역할을 합니다.

8. Docker보다는 로컬 환경에서 직접 개발하기

만약 Mac이나 Windows 환경에서 개발하는데 Docker를 띄워서 Next.js를 실행하고 계신다면, 로컬 환경(컴퓨터에 직접 Node를 깔아서 실행)에 비해 성능이 엄청나게 떨어지는 걸 겪게 되실 거예요.

Mac과 Windows에서 Docker가 파일 시스템에 접근하는 방식 때문에, 코드를 수정하고 반영되는 HMR 시간이 몇 초에서 길게는 몇 분까지 걸리기도 합니다. 똑같은 앱을 로컬 환경에 직접 띄우면 순식간에 HMR이 되는데 말이죠.

이런 성능 차이가 나는 이유는, Docker가 Linux 환경이 아닌 곳(Mac, Windows)에서 파일 시스템 작업을 처리할 때 중간에 번역하는 과정이 들어가기 때문이에요. 최상의 개발 경험을 원하신다면 이렇게 하세요:

  • 개발 중에는 Docker를 쓰지 말고, 로컬 환경에서 직접 스크립트를 실행(npm run dev 또는 pnpm dev)하세요.
  • Docker는 실서버 배포(production deployments)나 프로덕션 빌드 테스트 용도로만 남겨두세요.
  • 만약 회사 정책상 개발할 때 무조건 Docker를 써야만 한다면, Linux 머신이나 가상 머신(VM) 위에서 Docker를 구동하는 것을 고려해 보세요.

프로덕션 환경을 위한 Docker 배포 가이드도 참고해 보시면 좋습니다.

문제 원인을 찾기 위한 도구들 (Tools for finding problems)

여기까지 다 해봤는데도 느리다면, 도대체 어디서 병목이 생기는지 추적해 봐야겠죠?

1. 상세한 Fetch 로깅 (Detailed fetch logging)

next.config.js 파일에서 logging.fetches 옵션을 켜보세요. 개발 중에 백그라운드에서 어떤 데이터 통신이 일어나고 있는지 아주 자세한 정보를 볼 수 있습니다.

module.exports = {
  logging: {
    fetches: {
      fullUrl: true,
    },
  },
}

더 알아보기: Fetch 로깅 문서.

2. 터보팩 트레이싱 (Turbopack tracing)

터보팩 트레이싱(추적) 기능은 로컬 개발 중에 애플리케이션의 성능을 깊이 있게 이해할 수 있게 도와주는 도구예요. 각각의 모듈이 컴파일되는 데 시간이 얼마나 걸렸는지, 모듈들끼리 어떤 관계를 맺고 있는지 상세한 정보를 제공해 줍니다.

따라 해보세요:

  1. Next.js 최신 버전이 설치되어 있는지 확인합니다.

  2. 환경변수를 추가하여 터보팩 트레이스 파일을 생성하면서 개발 서버를 실행합니다:

    NEXT_TURBOPACK_TRACING=1 pnpm dev
    NEXT_TURBOPACK_TRACING=1 npm run dev
    NEXT_TURBOPACK_TRACING=1 yarn dev
    NEXT_TURBOPACK_TRACING=1 bun dev

  3. 애플리케이션 안에서 이곳저곳 페이지를 이동해 보거나 파일을 수정해서, 평소에 느렸던 그 상황(문제)을 똑같이 재현해 봅니다.

  4. Next.js 개발 서버를 종료합니다(Ctrl + C).

  5. 그러면 .next/dev 폴더 안에 trace-turbopack 이라는 파일이 생겼을 거예요.

  6. 터미널에 아래 명령어를 입력해서 이 파일을 분석합니다:

    npx next internal trace .next/dev/trace-turbopack

    만약 사용 중인 Next.js 버전에서 trace 명령어를 지원하지 않는다면, 예전 명령어인 turbo-trace-server를 써보세요:

    npx next internal turbo-trace-server .next/dev/trace-turbopack

  7. 트레이스 서버가 실행되면, 브라우저를 열고 https://trace.nextjs.org/ 에 접속해서 트레이스 결과를 시각적으로 확인할 수 있습니다.

  8. 기본적으로 트레이스 뷰어는 걸린 시간들을 합산(aggregate)해서 보여주는데요. 화면 우측 상단에서 "Aggregated in order(합산된 순서)"를 "Spans in order(개별 스팬 순서)"로 변경하면, 각각의 작업이 개별적으로 얼마나 걸렸는지 낱낱이 파악할 수 있어요.

알아두면 좋은 점 (Good to know): 트레이스 파일은 개발 서버 디렉터리 안에 저장되는데, 기본 경로가 .next/dev 입니다. 이 경로는 Next.js 설정 파일의 isolatedDevBuild 플래그를 통해 마음대로 바꿀 수 있습니다.

3. 그래도 아직 문제가 해결되지 않으셨나요? (Still having problems?)

위의 터보팩 트레이싱 섹션에서 생성한 트레이스 파일을 가지고 GitHub Discussions이나 Discord에 올려서 전 세계 개발자들과 Next.js 팀에게 도움을 요청해 보세요! 분명 좋은 답변을 얻으실 수 있을 거예요.

모든 문서에 대한 의미론적 개요(semantic overview)를 보시려면 https://nextjs.org/docs/sitemap.md 를 확인해 주세요.

사용 가능한 모든 문서의 인덱스(목록)를 보시려면 https://nextjs.org/docs/llms.txt 를 확인해 주세요.

profile
김동현
프론트에_가까운_풀스택_개발자
이전 포스트

How to implement JSON-LD in your Next.js application

다음 포스트

Enabling Next.js MCP Server for Coding Agents

0개의 댓글