안내서: Static Exports | Next.js

출처 URL: https://nextjs.org/docs/pages/guides/static-exports

Next.js 애플리케이션의 정적 내보내기를 생성하는 방법

마지막 업데이트 2026년 2월 20일

Next.js는 정적 사이트 또는 단일 페이지 애플리케이션(SPA)으로 시작한 뒤, 서버가 필요한 기능을 나중에 선택적으로 도입할 수 있게 해줍니다.

next build를 실행하면 Next.js는 라우트마다 HTML 파일을 생성합니다. 순수 SPA를 개별 HTML 파일로 분할하면, Next.js는 클라이언트 측에서 불필요한 JavaScript 코드를 불러오지 않아 번들 크기를 줄이고 더 빠른 페이지 로드를 가능하게 합니다.

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

구성

정적 내보내기를 활성화하려면 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 파일을 생성할 수 있습니다.

지원되는 기능

정적 사이트 구축에 필요한 대부분의 핵심 Next.js 기능을 지원합니다. 예를 들면 다음과 같습니다.

getStaticPaths를 사용하는 동적 라우트
next/link 사전 로드
JavaScript 프리로딩
Dynamic Imports
모든 스타일링 옵션(예: CSS Modules, styled-jsx)
클라이언트 측 데이터 패칭
getStaticProps
getStaticPaths

이미지 최적화

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

JavaScriptTypeScript

    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}`
    }

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

app/page.tsx

JavaScriptTypeScript

    import Image from 'next/image'

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

지원되지 않는 기능

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

국제화 라우팅
API Routes
Rewrites
Redirects
Headers
Proxy
Incremental Static Regeneration
기본 loader를 사용하는 Image Optimization
Draft Mode
fallback: true가 있는 getStaticPaths
fallback: 'blocking'이 있는 getStaticPaths
getServerSideProps

배포

정적 내보내기를 사용하면 HTML/CSS/JS 정적 에셋을 제공할 수 있는 모든 웹 서버에 Next.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;
      }

      # This is necessary when `trailingSlash: false`.
      # You can omit this when `trailingSlash: true`.
      location /blog/ {
          rewrite ^/blog/(.*)$ /blog/$1.html break;
      }

      error_page 404 /404.html;
      location = /404.html {
          internal;
      }
    }

버전 기록

버전	변경 사항
`v14.0.0`	`next export`가 `"output": "export"`로 대체되며 제거되었습니다.
`v13.4.0`	App Router(안정 버전)가 React Server Components와 Route Handlers 사용을 포함해 강화된 정적 내보내기 지원을 추가했습니다.
`v13.3.0`	`next export`가 더 이상 권장되지 않으며 `"output": "export"`로 대체되었습니다.

보내기