Question 1

Next.js 13 app 디렉터리에서 Fast Refresh(핫 리로딩)로 인해 발생하는 데이터베이스 연결 고갈 문제를 해결하는 방법

Accepted Answer

개발 모드에서는 Next.js Fast Refresh가 저장할 때마다 모듈을 다시 평가하므로, 최상위 레벨의 `new DatabaseConnection(...)`(또는 `postgres()`, PrismaClient 등)이 매번 새로운 연결을 생성하게 되고, 결국 PostgreSQL이 `remaining connection slots are reserved for non-replication superuser connections` 오류로 실패하게 됩니다. `globalThis`에 클라이언트를 캐싱하여 연결이 리로드 후에도 유지되도록 수정하세요:

```ts
import postgres from 'postgres';

declare module globalThis {
  let postgresSqlClient: ReturnType<typeof postgres> | undefined;
}

function connectOnceToDatabase() {
  if (!globalThis.postgresSqlClient) globalThis.postgresSqlClient = postgres();
  return globalThis.postgresSqlClient;
}

export const sql = connectOnceToDatabase();
```

동일한 싱글턴 패턴은 Prisma(`globalThis.prisma ??= new PrismaClient()`)와 다른 드라이버에도 적용됩니다. 이 문제는 개발 환경에만 영향을 미치며, 프로덕션 빌드에서는 요청마다 모듈을 다시 평가하지 않습니다.

Question 2

Next.js Pages Router 앱을 16.4로 업그레이드한 후 발생하는 Turbopack "module factory is not available" 하이드레이션 오류를 어떻게 해결하나요?

Accepted Answer

이는 Next.js 16.4.0에서 #97664로 도입된 알려진 Turbopack dev 회귀입니다. 페이지 청크 그룹이 `_app` 가용성 데이터를 재사용할 때 페이지 모듈이 클라이언트 청크에서 누락될 수 있으며, 이로 인해 SSR은 성공하지만 하이드레이션이 `module factory is not available` 오류와 함께 실패합니다.

근본적인 해결 방법: Pages Router 개발 클라이언트 모듈 그래프를 연결하는 PR #98823이 포함된 Next.js canary/preview 릴리스로 업그레이드하세요. 이 수정 사항은 `next@16.5.0-preview-358550b2-20261009`에서 검증되었습니다.

```bash
npm install next@canary
rm -rf .next
npm run dev
```

업그레이드할 수 없는 경우 다음 우회 방법 중 하나를 사용하세요:

```bash
# 영향을 받지 않는 마지막 릴리스로 다운그레이드
npm install next@16.3.8
rm -rf .next
npm run dev
```

또는 Turbopack 대신 webpack으로 개발 서버를 실행하세요:

```bash
npx next dev --webpack -p 3456
```

프로덕션 빌드는 영향을 받지 않으므로 16.4.0에서도 `next build && next start`가 정상적으로 작동합니다.

Question 3

Turbopack과 cacheComponents를 사용할 때 Next.js 16.4가 nonce 기반 CSP에서 하이드레이션에 실패하는 이유는 무엇인가요?

Accepted Answer

Next.js 16.4에서는 `experimental.turbopackSharedRuntime`이 기본적으로 활성화됩니다. `cacheComponents: true`인 경우, Turbopack은 요청 nonce를 추가하지 않고 청크 그룹 부트스트랩을 프리렌더링된 셸에 인라인합니다. `script-src 'self' 'nonce-'`과 같은 엄격한 CSP는 이 인라인 `

Question 4

Windows에서 Next.js standalone 출력이 .next/standalone 외부를 가리키는 symlink를 생성하는 문제를 어떻게 해결하나요?

Accepted Answer

Next.js를 **16.4.0 이상**으로 업그레이드하세요. 이 Windows 심볼릭 링크 문제가 해당 버전에서 수정되었습니다:

```bash
pnpm add next@^16.4.0
# or
yarn add next@^16.4.0
```

그런 다음 기존 빌드 출력을 삭제하고 다시 빌드하세요:

```bash
rm -r .next
pnpm build
```

이제 `.next/standalone/node_modules` 아래에 생성된 심볼릭 링크는 빌드 머신의 루트 `node_modules`나 절대 Windows 경로 대신 `.next/standalone/node_modules/.pnpm` 내부에서 해석됩니다. 이 버그는 pnpm을 사용하는 Windows 환경에서 Next.js 16.2.10 및 16.3.0으로 재현되었으며, yarn에서도 유사한 절대 경로 심볼릭 링크 동작이 보고되었습니다. 즉시 업그레이드할 수 없는 경우, 보고된 해결 방법은 Linux에서 standalone 출력을 빌드하거나 로컬 Windows 컨테이너 빌드에 webpack을 사용하는 것입니다.

Question 5

`distDir`가 Next.js 앱 외부를 가리킬 때 `next build`가 모노레포 파일을 삭제하지 못하도록 하려면 어떻게 해야 하나요?

Accepted Answer

Next.js는 빌드 전에 `distDir`을 지웁니다. `apps/web`에서 `distDir: "../../"`로 설정하면 확인되는 경로가 모노레포 루트가 되므로, Next.js가 해당 디렉터리를 재귀적으로 삭제합니다. `distDir`은 Next.js 프로젝트 루트 내부에 유지하세요:

1. `apps/web/next.config.ts`를 편집하여 안전하지 않은 설정을 제거하거나 로컬 디렉터리를 사용하세요:
```ts
const nextConfig = {
  distDir: '.next',
}
```
2. `distDir`이 리포지토리 루트, 홈 디렉터리, `/` 또는 다른 프로젝트를 가리키지 않도록 하세요.
3. Vercel 모노레포 배포의 경우 `.next`를 리포지토리 루트로 옮기는 대신, **Project Settings → General → Root Directory**로 이동하여 `apps/web`으로 설정하세요. 그러면 Vercel이 빌드 출력을 자동으로 감지합니다.
4. `apps/web`에서 빌드하기 전에 확인되는 경로를 검증하세요:
```bash
node -e "console.log(require('path').resolve('../../'))"
```
모노레포 루트나 관련 없는 파일이 포함된 다른 디렉터리가 출력되면 해당 구성은 안전하지 않은 것입니다.
5. 커스텀 `distDir` 안전 검증이 포함된 더 최신 릴리스로 Next.js `16.3.5`에서 업그레이드하세요.

삭제는 영구적이며 시스템 휴지통을 거치지 않습니다. 영향을 받은 파일은 Git 또는 다른 백업에서 복원하세요.

next.js

개요

README 미리보기

FAQ (5)

同类型项目

tensorflow

superpowers

everything-claude-code

flutter