Next.js 16 custom webpack 오류, 설정을 지우기 전에 번들러를 선택하세요

Next.js 16으로 올린 뒤 next build가 custom webpack 설정을 발견했다는 메시지와 함께 멈출 수 있다. 이때 next.config의 webpack 함수를 바로 지우면 빌드는 지나가도 SVG, alias, 모니터링 플러그인 같은 기능이 조용히 사라질 수 있다. 먼저 설정의 소유자와 역할을 적고, Webpack 유지와 Turbopack 이전 중 하나를 고른다.

Next.js 16 업그레이드 공식 문서에 따르면 버전 16부터 next dev와 next build는 Turbopack을 기본으로 쓴다. custom webpack 설정이 있으면 이를 모른 척하지 않도록 빌드를 멈춘다. 해결은 재설치가 아니라 번들러 선택이다.

Tap to zoom

webpack 설정을 누가 넣었는지 먼저 찾는다

프로젝트 루트에서 next.config.js, next.config.mjs, next.config.ts를 연다. 직접 작성한 webpack(config) { ... }가 있는지 찾고, 없다면 설정을 감싸는 플러그인을 확인한다.

rg -n "webpack|withSentryConfig|withMDX|svgr|resolve\.alias" next.config.* package.json

macOS나 Linux에서도 같은 rg 명령을 쓸 수 있다. rg가 없다면 편집기의 전체 검색으로 같은 단어를 찾는다. 공식 업그레이드 문서도 직접 정의하지 않았는데 이 오류가 난다면 플러그인이 webpack 옵션을 추가했을 수 있다고 안내한다.

찾은 줄마다 역할을 한 줄로 적는다.

• @svgr/webpack: SVG를 React 컴포넌트로 불러온다.
• config.resolve.alias: import 별칭을 바꾼다.
• 모니터링 플러그인: 빌드 결과에 소스맵이나 오류 수집 설정을 넣는다.
• 이름 모를 변경: 삭제하지 말고 해당 패키지의 현재 Next.js 16 지원 문서를 확인한다.

역할을 설명할 수 없는 설정은 먼저 지우지 않는다. AI에게 맡길 때도 “빌드를 고쳐 줘”보다 설정 블록과 담당 기능을 함께 주면 수정 범위를 좁힐 수 있다.

플러그인 의존이면 Webpack을 유지하고, 옮길 수 있는 규칙이면 Turbopack으로 간다

Tap to zoom

Next.js Turbopack 공식 문서는 next.config의 webpack() 함수를 Turbopack이 인식하지 않으며 webpack plugin도 지원하지 않는다고 설명한다. 반면 일부 webpack loader, alias, 확장자 규칙은 Turbopack 설정으로 옮길 수 있다.

다음 기준으로 경로를 고른다.

1. webpack plugin이나 미지원 loader API에 의존하면 당장은 Webpack을 유지한다. package.json의 build script를 next build --webpack으로 바꾸고, 플러그인의 Turbopack 지원 계획을 별도 과제로 남긴다.
2. alias, 확장자, 지원 loader처럼 공식 turbopack 옵션으로 표현할 수 있으면 이전한다.
3. 설정이 더는 쓰이지 않는다고 판단했다면 삭제 전후 빌드와 핵심 기능을 비교한다. 기억만으로 “불필요하다”고 결론 내리지 않는다.

next build --turbopack은 custom webpack 설정을 무시하고 Turbopack으로 진행하는 명시적 선택이다. 충돌 원인을 확인하는 비교 명령으로는 쓸 수 있지만, 기존 기능이 보존됐다는 증거는 아니다.

한 번에 한 경로만 바꾸고 diff를 남긴다

Webpack을 유지한다면 먼저 script만 명시적으로 바꾼다.

{
  "scripts": {
    "dev": "next dev",
    "build": "next build --webpack"
  }
}

Turbopack으로 옮긴다면 webpack 함수 전체를 자동 변환하려 하지 말고 기능별로 옮긴다. 예를 들어 SVG loader는 공식 설정 형식에서 다음처럼 표현할 수 있다.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  turbopack: {
    rules: {
      '*.svg': {
        loaders: ['@svgr/webpack'],
        as: '*.js',
      },
    },
  },
}

export default nextConfig

Turbopack 설정 문서는 rules, resolveAlias, resolveExtensions를 top-level turbopack 아래에 둔다고 설명한다. loader는 JavaScript를 반환해야 하고 일부 loader API는 지원되지 않는다. 예제가 실행된다고 모든 사용자 설정이 자동 호환되는 것은 아니다.

수정 뒤에는 git diff -- next.config.* package.json으로 범위를 본다. AI가 관련 없는 의존성이나 lockfile까지 바꿨다면 되돌리기 전에 그 변경이 필요한 근거부터 묻는다. AI가 만든 코드 저장 전 점검표처럼 파일 목록과 명령 결과를 분리해 남기면 재현이 쉬워진다.

기본 빌드와 핵심 경로를 같은 커밋에서 검증한다

Tap to zoom

두 번들러를 동시에 운영하라는 뜻이 아니다. 이전 전후를 비교할 짧은 검증 구간에서만 같은 커밋으로 결과를 남긴다.

npm run build
npx next build --webpack

최종 경로를 Turbopack으로 정했다면 첫 명령이 통과해야 한다. Webpack 유지가 결정이라면 build script가 --webpack을 포함하는지 확인하고 그 결과를 기준으로 삼는다. 이어서 다음을 확인한다.

• 홈과 동적 route가 열리는가.
• SVG, MDX, Sass처럼 custom 설정이 다룬 자산이 보이는가.
• alias import가 서버와 클라이언트 빌드에서 모두 해결되는가.
• 모니터링 플러그인이 맡았던 소스맵·오류 수집 결과가 남는가.
• CI와 배포 플랫폼이 로컬과 같은 build script를 실행하는가.

빌드 로그의 마지막 한 줄만 보지 말고 처음 나타난 구체적 오류를 남긴다. 배포에서만 실패한다면 Vercel 배포 로그에서 첫 원인을 찾는 순서로 환경 차이를 좁힌다.

--webpack은 실패가 아니라 명시적 선택이지만, 이유를 기록한다

--webpack으로 돌아가는 것은 지원되는 선택이다. 다만 이유 없이 영구 고정하면 다음 업그레이드에서 같은 판단을 반복한다. “모니터링 plugin이 Turbopack을 아직 지원하지 않음”, “custom loader가 emitFile에 의존함”처럼 현재 Webpack을 유지하는 한 문장 근거를 이슈나 README에 남긴다.

반대로 Turbopack 전환을 선택했다면 webpack 설정을 제거한 사실보다 그 기능이 어디로 옮겨졌는지를 기록한다. 오늘 할 일은 next.config의 설정 블록마다 담당 기능을 적고, 한 경로만 선택해 빌드한 뒤 핵심 페이지와 자산까지 통과한 결과를 남기는 것이다.

참고 출처

• How to upgrade to version 16 (Next.js)
• Turbopack (Next.js)
• next.config.js: turbopack (Next.js)
• next CLI (Next.js)

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.