[Next.js] Next.js의 Route Groups와 미들웨어를 이용한 인증 및 경로 충돌 문제 해결하기

 

Next.js Route Groups와 미들웨어를 이용한 인증 및 경로 충돌 문제 해결

 

Next.js의 app 디렉토리 구조와 Route Groups(경로 그룹) 기능을 활용하다 보면, 경로를 직관적이고 조직적으로 구성할 수 있지만 동일한 URL 경로로 해석되는 페이지를 두 개 이상 구성하게 되면 경로 충돌 문제가 발생할 수 있습니다. 이번 글에서는 로그인 상태에 따라 다른 페이지를 렌더링하는 과정에서 발생한 문제를 트러블슈팅한 과정과 미들웨어를 활용한 접근 제어 방법을 공유합니다.

 

---

🐛 문제 상황

프로젝트의 메인 페이지(/)에서 로그인 여부에 따라 다른 콘텐츠를 보여주고자 했습니다. 로그인 상태에 따라 별도의 경로 그룹을 활용해 다음과 같이 디렉토리를 구성했습니다.

src/ 
├──app/ 
│  ├── (private)/
│  │   └── page.tsx             // 로그인 시 렌더링될 페이지
│  ├── (public)/
│      └── page.tsx             // 비로그인 시 렌더링될 페이지
├── middleware.ts // 로그인 여부를 확인하는 미들웨어

• (public)/page.tsx: 비로그인 상태의 사용자에게 기본으로 보여줄 페이지(로그인 유도 콘텐츠)
• (private)/page.tsx: 로그인된 상태의 사용자에게 기본으로 보여줄 페이지(피드 콘텐츠)

 -> 이렇게 두 개의 경로 그룹을 사용해 로그인 전과 후에 서로 다른 페이지를 보여주고자 했습니다. 비로그인 사용자가 / 경로로 접속하면 (public)/page.tsx가 렌더링되고, 로그인된 사용자가 접근할 때는 (private)/page.tsx가 렌더링되도록 합니다.

 

---

⚠️ 문제 발생: 경로 충돌 오류

위와 같은 경로 그룹 설정은 동일한 URL을 가리키는 두 개의 병렬 경로 그룹이 생성되기 때문에, Next.js에서 아래와 같은 경로 충돌 오류가 발생했습니다.

Error: You cannot have two parallel pages that resolve to the same path. 
Please check /(private)/page and /(public)/page.

 

---

🤷‍♂️ 원인 분석

공식 문서를 살펴보니 Next.js에서는 경로 그룹 이름이 URL에 영향을 주지 않고, 단순히 디렉토리 구조를 위한 역할만 합니다. 즉, (public)/page.tsx와 (private)/page.tsx는 각각 다른 경로 그룹이지만 URL 상에서는 둘 다 동일한 / 경로로 해석됩니다.

 [참고: https://nextjs.org/docs/app/building-your-application/routing/route-groups]

 

Next.js 경로 그룹 관련 사항

1. 경로 그룹의 이름은 URL에 영향을 미치지 않음
   (public)와 (private)는 URL 구조를 변경하지 않고, Next.js 내부에서 경로를 구분(폴더를 조직화하기 위한 역할)하기 위한 역할만 합니다. 따라서, (public)/page.tsx와 (private)/page.tsx는 모두 동일한 / 경로로 인식됩니다.
   
   
2. 중복된 경로 오류 발생(병렬 경로는 동일한 URL을 가질 수 없음)
   동일한 경로에 대해 두 개의 페이지가 존재할 경우 Next.js는 경로 충돌을 방지하기 위해 오류를 발생시킵니다. 경로 그룹을 이용해 디렉토리를 구성해도, 동일한 URL(/)에 두 개의 페이지가 존재할 수 없으므로 오류가 발생하게 됩니다.

 

---

✅ 해결 방법: 경로 그룹을 구분하고 미들웨어로 접근 제어하기

이 문제를 해결하기 위해 미들웨어를 활용하여 특정 경로에 대한 접근을 제어하는 방식을 채택했습니다. 미들웨어를 사용함으로써 로그인 상태에 따라 /feed와 같은 보호 경로 접근을 제어할 수 있었으며, 클라이언트 측 조건부 렌더링이 아닌 서버 측에서 처리함으로써 보안성과 성능 최적화 효과를 동시에 얻을 수 있었습니다.

 

왜 미들웨어를 사용했을까?

1. 보안성: 클라이언트 측 조건부 렌더링의 한계

만약 layout.tsx 나 page.tsx에서 토큰 값을 가져와 조건부 렌더링을 통해 페이지 접근을 제어하려 한다면, 클라이언트 측에서 조건부로 페이지를 숨기는 방식이 됩니다. 이 방식은 다음과 같은 단점을 가집니다.

• 클라이언트에서 콘텐츠가 잠시라도 로드될 수 있음: 클라이언트 측 조건부 렌더링은 페이지가 이미 로드된 이후에 조건에 따라 내용을 보여주거나 숨깁니다. 이 과정에서 비로그인 사용자가 보호된 콘텐츠의 일부를 잠시라도 볼 수 있는 가능성이 있습니다.
• 보호가 필요한 콘텐츠를 완전히 차단하기 어려움: 클라이언트 측에서 콘텐츠를 조건부로 렌더링할 경우, 실제로는 사용자가 보호된 페이지를 요청하고 로드한 후에 해당 콘텐츠가 숨겨지게 됩니다. 이는 보안 측면에서 완전한 접근 제어가 어렵게 만듭니다.

반면, 미들웨어는 서버 측에서 클라이언트 요청이 처리되기 전에 접근을 제어하므로, 보호된 페이지에 대한 요청 자체를 차단합니다. 토큰이 없는 사용자는 서버 측에서부터 보호된 콘텐츠에 접근할 수 없도록 설정할 수 있습니다.

2. 성능 최적화: 불필요한 페이지 로드를 방지

클라이언트 측에서 조건부 렌더링을 한다면, 비로그인 사용자가 보호된 페이지에 접근할 때도 페이지가 로드됩니다. 예를 들어 /feed 페이지에 접근할 때, 비로그인 사용자는 콘텐츠 로드 후에야 접근이 제한되었다는 메시지를 보게 될 수 있습니다. 이 방식은 두 가지 성능 문제를 야기합니다.

• 불필요한 데이터 요청: 클라이언트는 서버에서 해당 페이지와 관련된 데이터와 리소스를 받아오게 되어, 불필요한 네트워크 요청과 데이터 전송이 발생합니다.
• 초기 로딩 지연: 페이지를 먼저 로드한 후에 조건부로 콘텐츠를 숨기기 때문에, 실제로 비로그인 사용자가 접근할 수 없는 페이지임에도 불구하고 초기 로딩이 발생하여 UX가 저하됩니다.

미들웨어는 요청 단계에서 바로 리디렉션을 처리하기 때문에, 비로그인 사용자가 접근할 수 없는 페이지에 대해 불필요한 로딩이 발생하지 않습니다. 그 결과, 비로그인 사용자는 /login과 같은 로그인 페이지로 즉시 리디렉션되어 페이지 로딩과 네트워크 요청을 최적화할 수 있습니다.

3. 일관된 사용자 경험: 빠른 리디렉션 처리

미들웨어는 요청이 서버에서 처리되는 단계에서 토큰 유무에 따라 즉시 리디렉션하므로, 비로그인 사용자가 보호된 페이지에 접근하려 할 때 빠르게 로그인 페이지로 리디렉션됩니다.

• 페이지 전환의 일관성: 미들웨어에서 요청을 제어하면, 비로그인 사용자는 보호된 페이지에 접근하려 할 때 직접 /login 페이지로 이동합니다. 이는 사용자가 중간에 다른 페이지나 경고 메시지를 볼 필요 없이 일관된 UX 흐름을 유지하게 합니다.
• 즉각적인 피드백 제공: 클라이언트 측 조건부 렌더링에서는 페이지가 로드된 이후에야 접근 불가 메시지를 볼 수 있는 반면, 미들웨어를 통해 즉시 리디렉션하면 사용자는 빠르게 로그인 필요 상태를 인지할 수 있습니다.

미들웨어를 사용해 서버 측에서 토큰 검사를 진행함으로써, 보안성, 성능 최적화, 그리고 일관된 사용자 경험을 모두 보장할 수 있습니다. 클라이언트 측 조건부 렌더링은 페이지를 숨기는 데 적합하지 않으며, 보호된 콘텐츠에 대한 완전한 접근 제어가 어렵습니다. 반면 미들웨어는 사용자가 콘텐츠에 접근하기 전 요청을 차단하므로, 더 강력하고 효율적인 방식으로 보호된 페이지 접근을 관리할 수 있습니다.

 

---

📍 최종 구현: 미들웨어로 접근 제어 처리

미들웨어에서 특정 경로에 대한 접근 제어를 추가하여 보호 경로에 비로그인 사용자가 접근할 경우 /로 리디렉션하는 구조로 변경했습니다.

결과적으로, 아래와 같이 디렉토리 구조를 수정했습니다.

src/ 
├──app/ 
│  ├── (private)/
│  │   └── page.tsx // 로그인되지 않은 사용자에게 보여줄 페이지
│  ├── (public)/
│      ├── feed/
│          └── page.tsx // 로그인된 사용자만 접근 가능한 피드 페이지
├── middleware.ts // 로그인 상태에 따라 접근을 제어하는 미들웨어

• (public)/page.tsx: 여전히 로그인하지 않은 사용자를 위한 기본 페이지로 사용합니다.
• (private)/feed/page.tsx: 로그인한 사용자를 위한 피드 페이지로, /feed 경로로 접근할 수 있습니다. 이 페이지는 로그인된 상태에서만 접근하도록 설정합니다.
• middleware.ts: /feed 경로에 접근할 때 로그인 상태를 확인하여, 로그인되지 않은 사용자는 / 페이지로 리디렉션하도록 설정합니다.

 

미들웨어를 설정하여 로그인 여부에 따라 /feed, /profile, /post, /search 등 특정 경로에 대한 접근을 제어합니다.

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const token = request.cookies.get('userToken'); // 로그인 상태 확인
  const { pathname } = request.nextUrl;

  // 보호가 필요한 경로들을 정의
  const protectedPaths = ['/feed', '/profile', '/post', '/search'];

  // 로그인되지 않은 사용자가 보호 경로에 접근하면 /로 리디렉션
  if (!token && protectedPaths.some((path) => pathname.startsWith(path))) {
    return NextResponse.redirect(new URL('/', request.url));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/:path*'], // 모든 경로에 대해 미들웨어 적용 후 조건부로 제어
};

 

• 로그인 상태 확인: userToken 쿠키를 통해 사용자가 로그인 상태인지 확인합니다.
• 보호 경로 조건: 로그인 상태에 따라 접근을 제어해야 하는 경로(/feed, /profile, /post, /search 등)를 하나의 protectedPaths 배열로 관리하고, 비로그인 사용자의 접근을 막습니다.
• 리디렉션 처리: 보호된 경로에 비로그인 사용자가 접근하면 /로 리디렉션하고 로그인된 사용자만 피드 페이지에 접근할 수 있습니다.

 

---

⭐️ 결론

Next.js에서 경로 그룹(Route Groups)은 디렉토리 구조를 깔끔하게 정리하는 데 유용하지만, URL에 영향을 미치지 않으므로 동일한 경로에서 조건부 렌더링이 필요할 때 충돌 문제가 발생할 수 있습니다. 이를 해결하기 위해 미들웨어를 활용하여 로그인 여부에 따라 특정 경로 접근을 제어하는 방식을 도입했습니다.

• 경로 그룹의 특성 이해: 경로 그룹은 디렉토리 정리를 위한 것이지, URL 자체에 영향을 주지 않는다는 점을 유의해야 합니다.
• 미들웨어를 활용한 접근 제어: 보호된 경로를 정의하고, 미들웨어를 통해 조건부 접근 제어를 구현함으로써 더 나은 사용자 경험을 제공할 수 있었습니다.
• 로그인 여부에 따라 다른 콘텐츠 제공: 미들웨어로 인증 상태를 확인하여, 사용자의 로그인 상태에 따라 동적으로 다른 페이지 콘텐츠를 제공할 수 있었습니다.