NextJS: Static HTML Export

예제: Static Export
next export는 Next.js 애플리케이션을 정적 HTML로 내보내서 Node.js 서버 없이 렌더링할 수 있게 합니다. 다음과 같은 지원되지 않는 기능이 필요하지 않은 경우에만 next export를 사용하는 것이 좋습니다.

오직 일부 페이지만 정적 HTML로 미리 렌더링하려는 하이브리드 사이트를 구축하려는 경우에는 Next.js가 자동으로 수행하는 Automatic Static Optimization과 Incremental Static Regeneration(https://nextjs.org/docs/basic-features/data-fetching/incremental-static-regeneration)에 대해 자세히 알아보세요.

next export

다음과 같이 output: "export"를 포함하는 next.config.js 파일을 업데이트합니다.

/**
 * @type {import('next').NextConfig}
 */
const nextConfig = {
  output: 'export',
};

module.exports = nextConfig;

다음과 같이 package.json 파일의 스크립트를 업데이트하여 next export를 포함합니다.

"scripts": {
  "build": "next build && next export"
}

npm run build를 실행하면 out 디렉터리가 생성됩니다.

next export는 앱의 HTML 버전을 빌드합니다. next build 중에 getStaticProps와 getStaticPaths는 페이지 디렉토리의 각 페이지(동적 경로의 경우 더 많음)에 대해 HTML 파일을 생성합니다. 그런 다음 next export는 이미 내보낸 파일을 올바른 디렉토리로 복사합니다. getInitialProps는 next build 대신 next export 중에 HTML 파일을 생성합니다.

더 고급진 시나리오에서는 next.config.js 파일의 exportPathMap이라는 매개변수를 정의하여 생성될 페이지를 구성할 수 있습니다.

경고: getStaticPaths를 사용하는 페이지의 경우 exportPathMap을 사용하여 경로를 정의하면 무시되고 덮어씌워집니다. 함께 사용하지 않는 것을 권장합니다.

지원되는 기능

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

• getStaticPaths를 사용하는 동적 경로
• next/link로 prefetching
• JavaScript 사전로드
• 동적 임포트(Dynamic imports)
• 모든 스타일링 옵션(CSS Modules, styled-jsx 등)
• 클라이언트 측 데이터 가져오기
• getStaticProps
• getStaticPaths
• 커스텀 로더를 사용한 이미지 최적화

지원되지 않는 기능

node.js 서버를 필요로하거나 빌드 프로세스 중에 계산할 수 없는 동적 로직이 필요한 기능들은 지원되지 않습니다:

• 이미지 최적화 (기본 로더)
• 국제화 라우팅
• API 라우트
• 리다이렉트
• 헤더
• 미들웨어
• 증분형 정적 생성
• fallback 속성을 사용하는 getStaticPaths
• fallback 속성을 'blocking'으로 사용하는 getStaticPaths
• getServerSideProps
• getInitialProps

getInitialProps를 사용하면 getStaticProps 대신 사용할 수 있지만 몇 가지 주의 사항이 있습니다:

• getInitialProps는 동적 경로가 없는 모든 페이지에서 getStaticProps 또는 getStaticPaths와 함께 사용할 수 없습니다. 동적 경로가 있는 경우 getStaticPaths 대신 next.config.js 파일의 exportPathMap 매개 변수를 구성하여 익스포터가 어떤 HTML 파일을 출력해야 하는지 알려주어야 합니다.
• getInitialProps가 내보내기 중에 호출될 때, 컨텍스트 매개 변수의 req 및 res 필드는 서버가 실행되지 않기 때문에 빈 개체입니다.
• getInitialProps는 클라이언트 사이드 내비게이션마다 호출됩니다. 빌드 시간에만 데이터를 가져오려면 getStaticProps로 전환하십시오.
• getInitialProps는 API에서 가져와야 하며 getStaticProps와 달리 Node.js 특정 라이브러리나 파일 시스템을 사용할 수 없습니다.

가능한 한 getStaticProps로 이전하는 것이 좋습니다.