생산성

Next.js App Router에서 클로드 API 스트리밍 응답 끊김 현상: Server Actions 충돌 원인과 Route Handler 전환 해결법

March 22, 2026 5 min read 한국어
Next.js App Router에서 클로드 API 스트리밍 응답 끊김 현상: Server Actions 충돌 원인과 Route Handler 전환 해결법

클로드 API를 Next.js App Router에 붙이고 나서 첫 응답까지 8~12초를 기다린 적 있으세요? Server Actions 위에서 스트리밍을 시도했더니 청크가 뚝뚝 끊기거나, 아예 전체 응답이 다 완성된 뒤에야 한 번에 화면에 뿌려지는 경험이요. 2026년 현재 Next.js 15 + Anthropic Claude API 조합을 쓰는 팀의 절반 이상이 이 문제로 시간을 날리고 있어요.

문제는 단순한 네트워크 지연이 아니에요. Server Actions의 직렬화 모델, App Router의 렌더링 경계, 그리고 클로드 API의 SSE(Server-Sent Events) 방식이 세 겹으로 충돌하는 구조적 이슈예요. 코드 몇 줄 고친다고 해결되지 않는 이유가 여기 있어요.

이 글에서 다루는 것들:

  • Server Actions가 스트리밍과 충돌하는 근본 원인
  • Route Handlers로 전환했을 때 실제 성능 차이
  • ReadableStream vs TransformStream 선택 기준
  • 2026년 기준 프로덕션에서 검증된 패턴

핵심 요약

  • 클로드 API 스트리밍 응답을 Next.js App Router Server Actions에서 직접 반환하면, Server Actions의 JSON 직렬화 과정이 SSE 스트림을 가로막아 청크 단위 전달이 불가능해져요.
  • Next.js 15 기준, Server Actions는 Response 객체 반환을 공식 지원하지 않아 스트리밍 끊김 현상이 구조적으로 발생해요.
  • Route Handlers(app/api/[...]/route.ts)로 전환하면 ReadableStream을 그대로 반환할 수 있어, 첫 청크까지 걸리는 시간(TTFB)이 평균 610초에서 0.81.2초로 줄어드는 패턴이 다수 보고되고 있어요.
  • experimental_StreamingText 같은 우회 방법보다, API 레이어를 Route Handler로 분리하고 클라이언트에서 fetch + ReadableStreamDefaultReader로 읽는 게 2026년 기준 가장 안정적인 패턴이에요.

Server Actions가 스트리밍을 막는 구조적 이유

Server Actions는 원래 폼 제출, 데이터 뮤테이션처럼 요청-응답이 딱 한 번 오가는 패턴을 위해 설계됐어요. 내부적으로 보면, Server Actions는 모든 반환값을 JSON으로 직렬화해서 클라이언트로 보내요. Promise<string>은 괜찮아요. 그런데 ReadableStream이나 AsyncIterable은요? JSON으로 표현할 수 없으니, 직렬화 시점에 전체 스트림이 소비되거나 에러가 나요.

Next.js 15 릴리즈 노트(frontoverflow.com, 2024)를 보면 Server Actions에 use server 지시어를 붙인 함수는 응답을 클라이언트 바운더리까지 직렬화하는 파이프라인을 반드시 거쳐야 한다고 명시돼 있어요. 이게 바로 클로드 API 스트리밍 응답이 App Router Server Actions에서 끊기는 핵심 원인이에요.

쉽게 말하면 이래요.

클로드 API → SSE 청크 스트림 → Server Action 직렬화 레이어 → 💥 전체 버퍼링 → 클라이언트

청크가 쪼개져서 오지 않고, 전부 모인 뒤에야 한 덩어리로 내려오는 거예요. 그래서 화면에서 “로딩 중…” 스피너만 10초 돌다가 갑자기 전체 답변이 팍 나타나는 경험을 하게 되는 거고요.

Anthropic 공식 문서에 따르면 Claude API의 스트리밍은 text/event-stream 형식의 SSE를 써요. 각 청크는 event: content_block_delta 이벤트로 순차 전달되는 구조인데, Server Actions 레이어가 이 흐름을 완전히 끊어버리는 셈이에요.

Route Handler로 분리하면 무슨 일이 생기나

해결책은 생각보다 명확해요. 스트리밍 엔드포인트는 Server Actions 밖으로 빼야 해요. app/api/chat/route.ts처럼 Route Handler를 따로 만들면, Response 객체에 ReadableStream을 담아 그대로 반환할 수 있거든요.

실제 코드 흐름을 보면 이래요:

// app/api/chat/route.ts
import Anthropic from "@anthropic-ai/sdk";

export async function POST(req: Request) {
  const { messages } = await req.json();
  const client = new Anthropic();

  const stream = await client.messages.stream({
    model: "claude-opus-4-5",
    max_tokens: 1024,
    messages,
  });

  const readable = new ReadableStream({
    async start(controller) {
      for await (const chunk of stream) {
        if (
          chunk.type === "content_block_delta" &&
          chunk.delta.type === "text_delta"
        ) {
          controller.enqueue(new TextEncoder().encode(chunk.delta.text));
        }
      }
      controller.close();
    },
  });

  return new Response(readable, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}

클라이언트에서는 fetch로 이 엔드포인트를 호출하고 response.body.getReader()로 읽으면 돼요. React useState로 누적 텍스트를 관리하면 타이핑되는 효과도 자연스럽게 나오고요.

ReadableStream vs TransformStream: 언제 뭘 쓰나

기준ReadableStreamTransformStream
용도단순 청크 전달청크 변환·필터링 필요 시
복잡도낮음중간
에러 핸들링controller.error()writable 쪽에서 처리
백프레셔 지원기본 지원세밀하게 제어 가능
추천 상황클로드 API 텍스트 단순 스트리밍마크다운 파싱, 필터링, 로깅 삽입

단순 채팅 인터페이스라면 ReadableStream으로 충분해요. 스트리밍 중에 마크다운을 변환하거나 특정 토큰을 필터링해야 한다면 TransformStream을 중간에 끼워 넣는 게 깔끔하고요.

CORS 문제도 같이 온다

Route Handler로 분리하면 또 하나의 문제가 따라와요. 클라이언트에서 /api/chat을 직접 호출하는 건 같은 도메인이라 괜찮은데, 외부 도메인이나 개발 환경에서 프록시를 쓸 때 CORS 에러가 튀어나와요. route.ts에 OPTIONS 핸들러를 추가하고 헤더를 명시해줘야 해요.

export async function OPTIONS() {
  return new Response(null, {
    headers: {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Methods": "POST, OPTIONS",
      "Access-Control-Allow-Headers": "Content-Type",
    },
  });
}

프로덕션에서 자주 빠지는 함정 세 가지

타임아웃 설정 미스

Vercel 기본 함수 타임아웃은 10초(Pro 플랜 기준 60초)예요. 클로드가 긴 응답을 생성할 때 이 한도를 넘으면 스트림이 중간에 뚝 끊겨요. next.config.ts의 serverActions 설정이 아니라 Vercel 대시보드나 vercel.json의 functions 블록에서 maxDuration을 조정해야 해요. 처음 이 함정에 빠지면 코드를 한참 들여다보다가 결국 배포 설정 문제였다는 걸 뒤늦게 알게 돼요.

에러 시 스트림 미종료

네트워크 이슈나 API 에러 발생 시 controller.close() 또는 controller.error()를 명시적으로 호출하지 않으면, 클라이언트는 스트림이 언제 끝나는지 알 수 없어서 무한 대기 상태가 돼요. try-finally 블록으로 종료를 보장해야 해요.

한글 인코딩 깨짐

TextEncoder는 기본적으로 UTF-8이라 한글이 깨지지 않아요. 그런데 응답 헤더에 Content-Type: text/plain만 쓰고 charset=utf-8을 빠뜨리면 일부 브라우저에서 깨질 수 있어요. 헤더 명시는 필수예요.

지금 당장 적용할 수 있는 체크리스트

지금 Server Actions로 스트리밍을 구현했고 끊김이 있다면, 순서대로 따라가 보세요.

  1. 당장 이번 주: app/api/stream/route.ts를 만들고 스트리밍 로직을 여기로 이전하세요. Server Actions는 폼 제출, 캐시 무효화, DB 뮤테이션에만 써요. 스트리밍은 Server Actions의 영역이 아니에요.

  2. 다음 배포 전 확인: Vercel 함수 타임아웃, Content-Type 헤더, try-finally 에러 처리 세 가지를 반드시 점검하세요.

  3. 3개월 뒤를 보려면: Anthropic이 2026년 상반기 중 claude-opus-5 계열 모델 출시를 예고한 상황이에요. 응답 속도와 토큰당 비용이 변동될 수 있으니, 스트리밍 레이어를 모델 파라미터와 분리해두는 게 유리해요. model 값을 환경변수로 빼두는 것만으로도 나중에 코드를 건드릴 필요가 없어요.

마치며: 구조가 맞아야 스트리밍도 산다

클로드 API 스트리밍이 App Router에서 끊기는 건 코드 버그가 아니라 레이어 경계 설계 문제예요. Server Actions는 뮤테이션, Route Handlers는 스트리밍. 이 분리만 지켜도 대부분의 끊김 문제는 사라져요.

  • Server Actions ≠ 스트리밍 엔드포인트
  • Route Handler + ReadableStream = 클로드 API 스트리밍의 올바른 그릇
  • 타임아웃, 에러 처리, 인코딩 헤더는 체크리스트로 관리
  • 모델명과 설정은 환경변수로 분리해서 유연하게 유지

2026년 기준, Next.js App Router와 AI API의 조합은 표준 스택이 돼가고 있어요. 그런데 아직도 Server Actions로 스트리밍을 시도하다 허비하는 시간이 너무 많아요. 구조를 한 번 바로잡으면, 그다음은 훨씬 빠르게 달릴 수 있거든요.

여러분 팀은 지금 스트리밍 레이어를 어디에 두고 있나요?

참고자료

  1. 클로드 AI 오류 해결 | 응답지연 메시지제한 로그인문제 브라우저호환성 - 유용한 지식 공유
  2. [Next.js] CORS 에러 해결하기 (api 설정하기)
  3. Next.js 15 - Next.js 15에서 업데이트 되는 내용들

Photo by Bluestonex on Unsplash

클로드 스트리밍 TypeScript

Related Posts