Next.js 16 업그레이드 후 경로 별칭을 Turbopack 방식으로

next.config.ts에서 webpack 방식의 alias 설정을 turbopack.resolveAlias로 변경했다. Next.js 16으로 메이저 업그레이드하면서 빌드 엔진이 바뀌니 설정도 함께 맞춰야 하는 작업이었다.

Next.js 16과 빌드 엔진의 변화

Next.js 16이 나오면서 기본 빌드 시스템이 Rust 기반의 Turbopack으로 전환되기 시작했다. 이건 단순히 "더 빠른 빌드"라는 수준의 변화가 아니라, 빌드 파이프라인 자체의 근본적인 변경을 의미한다. 우리가 next.config.ts에 작성하던 webpack 관련 설정들이 더 이상 작동하지 않거나, 호환되지 않는 경우가 생기게 되는 거다.

특히 경로 alias는 SEO에도 영향을 미치는 부분이다. 상대 경로 대신 절대 경로를 쓸 수 있게 해주는 alias는 코드의 가독성뿐 아니라 import 구조의 일관성과도 직결되는데, 이게 제대로 작동하지 않으면 빌드 단계에서 에러가 나거나 최악의 경우 잘못된 경로로 번들링되어 사이트 맵이나 sitemap.xml 생성에 문제가 생길 수 있다.

마이그레이션: webpack.resolve.alias → turbopack.resolveAlias

next.config.ts의 구조를 정리하면 이렇게 변했다:

구체적으로는 next.config.ts에서 이런 식으로 변경된다:

// Before (Next.js 15)
export default {
  webpack: {
    resolve: {
      alias: {
        '@': path.resolve(__dirname, 'src/'),
        '@components': path.resolve(__dirname, 'src/components/'),
      }
    }
  }
}

// After (Next.js 16)
export default {
  turbopack: {
    resolveAlias: {
      '@': './src',
      '@components': './src/components',
    }
  }
}

turbopack 방식에서는 절대 경로를 쓰지 않고 상대 경로로 정의한다는 게 핵심이다. 이건 Turbopack의 모듈 해석 방식이 다르기 때문이고, 개발 환경과 프로덕션 빌드 양쪽에서 일관되게 작동하도록 설계된 것이다.

왜 이 변경이 SEO 관련 fix인가?

commit 메시지에 "(seo)" 라벨이 붙은 이유는 이 alias 설정이 제대로 작동하지 않으면 동적 라우팅이나 메타데이터 생성 로직에 영향을 미치기 때문이다. 예를 들어 @config로 import한 설정 파일에서 canonical URL을 정의하거나, @utils/seo에서 schema.org 마크업을 생성할 때 이 경로가 제대로 해석되지 않으면 빌드 에러가 나거나 잘못된 값이 삽입될 수 있다. 결과적으로 Open Graph 태그가 누락되거나 sitemap 생성이 실패하는 상황으로 이어질 수 있으니까, SEO 배포 이전에 반드시 검증해야 하는 부분인 거다.

마이그레이션 시 주의점

이런 유형의 마이그레이션을 할 때 자주 놓치는 함정들:

• tsconfig.json의 baseUrl과 paths와 중복 정의하지 않기: 타입스크립트의 경로 매핑과 Turbopack의 resolveAlias가 겹치면 우선순위 문제로 혼란스러운 버그가 생길 수 있다. 한 곳에만 정의하고 다른 곳은 참조하는 구조가 낫다.
• 개발 서버 재시작 필수: webpack 설정 변경 때와 달리 Turbopack은 next.config.ts 변경 후 자동 리로드가 항상 완벽하지 않을 수 있으니 개발 서버를 완전히 재시작하는 게 안전하다.
• CI/CD 환경에서도 동일하게 테스트하기: 로컬에서는 작동하는데 CI에서 빌드가 깨지는 경우가 있으니, 본 배포 전에 한 번은 상수 환경에서 전체 빌드를 돌려봐야 한다.

회고

Next.js의 메이저 업그레이드는 단순히 버전 번호를 올리는 게 아니라 기반 기술 스택이 바뀌는 것이라 관련된 모든 설정을 다시 점검해야 한다. 이번 작업을 통해 webpack의 설정 방식과 Turbopack의 설정 방식이 얼마나 다른지, 그리고 단순한 "기술 업그레이드"가 실제로는 여러 레이어에 걸쳐 영향을 미친다는 걸 다시 한 번 확인했다. 팀원들이 Next.js 16으로 올라갈 때 이런 설정 마이그레이션이 필요하다는 걸 문서화해두는 것도 중요한 부분이다.

🛒 이 글과 어울리는 추천 상품

• 외장SSD 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.