Static Exports

Next.js는 처음에 정적 사이트 또는 단일 페이지 애플리케이션(SPA)으로 시작한 후, 나중에 서버가 필요한 기능을 선택적으로 업그레이드할 수 있게 합니다.

next build를 실행하면 Next.js는 경로마다 HTML 파일을 생성합니다. 엄격한 SPA를 개별 HTML 파일로 나누어, Next.js는 클라이언트 측에서 불필요한 JavaScript 코드를 로드하지 않게 하여 번들 크기를 줄이고 페이지 로드를 빠르게 할 수 있습니다.

Next.js는 이 정적 내보내기를 지원하므로 HTML/CSS/JS 정적 자산을 제공할 수 있는 모든 웹 서버에 배포하고 호스팅할 수 있습니다.

Configuration

정적 내보내기를 활성화하려면 next.config.js 파일에서 출력 모드를 변경합니다:

next.config.js

/**
 * @type {import('next').NextConfig}
 */
const nextConfig = {
  output: 'export',
 
  // Optional: Change links `/me` -> `/me/` and emit `/me.html` -> `/me/index.html`
  // trailingSlash: true,
 
  // Optional: Prevent automatic `/me` -> `/me/`, instead preserve `href`
  // skipTrailingSlashRedirect: true,
 
  // Optional: Change the output directory `out` -> `dist`
  // distDir: 'dist',
}
 
module.exports = nextConfig

next build를 실행한 후, Next.js는 애플리케이션의 HTML/CSS/JS 자산을 포함한 out 폴더를 생성합니다.

getStaticProps 및 getStaticPaths를 활용하여 pages 디렉토리의 각 페이지(또는 동적 경로에 대한 추가 페이지)에 대한 HTML 파일을 생성할 수 있습니다.

Supported Features

정적 사이트를 구축하는 데 필요한 대부분의 핵심 Next.js 기능이 지원됩니다:

getStaticPaths를 사용할 때의 동적 경로
next/link를 통한 프리페칭
JavaScript 사전 로드
동적 가져오기
모든 스타일링 옵션(e.g. CSS Modules, styled-jsx)
클라이언트 측 데이터 가져오기
getStaticProps
getStaticPaths

Image Optimization

Image Optimization은 next/image를 통해 정적 내보내기와 함께 사용할 수 있으며, next.config.js에서 커스텀 이미지 로더를 정의할 수 있습니다. 예를 들어, Cloudinary와 같은 서비스를 사용하여 이미지를 최적화할 수 있습니다:

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    loader: 'custom',
    loaderFile: './my-loader.ts',
  },
}
 
module.exports = nextConfig

이 커스텀 로더는 원격 소스에서 이미지를 가져오는 방법을 정의합니다. 예를 들어, 다음 로더는 Cloudinary를 위한 URL을 구성합니다:

my-loader.ts

export default function cloudinaryLoader({
  src,
  width,
  quality,
}: {
  src: string
  width: number
  quality?: number
}) {
  const params = ['f_auto', 'c_limit', `w_${width}`, `q_${quality || 'auto'}`]
  return `https://res.cloudinary.com/demo/image/upload/${params.join(
    ',',
  )}${src}`
}

my-loader.js

export default function cloudinaryLoader({ src, width, quality }) {
  const params = ['f_auto', 'c_limit', `w_${width}`, `q_${quality || 'auto'}`]
  return `https://res.cloudinary.com/demo/image/upload/${params.join(
    ',',
  )}${src}`
}

그런 다음 애플리케이션에서 next/image를 사용하여 Cloudinary의 이미지에 대한 상대 경로를 정의할 수 있습니다:

app/page.tsx

import Image from 'next/image'
 
export default function Page() {
  return <Image alt="turtles" src="/turtles.jpg" width={300} height={300} />
}

app/page.js

import Image from 'next/image'
 
export default function Page() {
  return <Image alt="turtles" src="/turtles.jpg" width={300} height={300} />
}

Unsupported Features

Node.js 서버가 필요하거나 빌드 과정에서 계산할 수 없는 동적 로직을 요구하는 기능은 지원되지 않습니다:

Internationalized Routing
API Routes
Rewrites
Redirects
Headers
Middleware
Incremental Static Regeneration
기본 loader를 사용하는 Image Optimization
Draft Mode
fallback: true를 사용하는 [getStaticPaths]
fallback: 'blocking'를 사용하는 [getStaticPaths]
getServerSideProps

Deploying

정적 내보내기를 통해 Next.js는 HTML/CSS/JS 정적 자산을 제공할 수 있는 모든 웹 서버에 배포하고 호스팅할 수 있습니다.

next build를 실행하면, Next.js는 정적 내보내기를 out 폴더에 생성합니다. 예를 들어, 다음과 같은 경로가 있다고 가정해 봅시다:

/
/blog/[id]

next build를 실행한 후, Next.js는 다음 파일들을 생성할 것입니다:

/out/index.html
/out/404.html
/out/blog/post-1.html
/out/blog/post-2.html

Nginx와 같은 정적 호스트를 사용하는 경우, 들어오는 요청을 올바른 파일로 리디렉션하도록 재작성할 수 있습니다:

nginx.conf

server {
  listen 80;
  server_name acme.com;
 
  root /var/www/out;
 
  location / {
      try_files $uri $uri.html $uri/ =404;
  }
 
  # `trailingSlash: false`인 경우 필요합니다.
  # `trailingSlash: true`인 경우 생략할 수 있습니다.
  location /blog/ {
      rewrite ^/blog/(.*)$ /blog/$1.html break;
  }
 
  error_page 404 /404.html;
  location = /404.html {
      internal;
  }
}

Version History

Version	Changes
`v14.0.0`	`next export`는 `"output": "export"`로 대체되었습니다.
`v13.4.0`	App Router (Stable)은 React Server Components와 Route Handlers를 사용한 향상된 정적 내보내기 지원을 추가합니다.
`v13.3.0`	`next export`는 더 이상 사용되지 않으며 `"output": "export"`로 대체되었습니다.

Production Checklist Multi Zones