v3
Nuxt on GitHub

프리렌더링

Nuxt는 페이지를 빌드 시 정적으로 렌더링하여 특정 성능 또는 SEO 지표를 향상시킬 수 있습니다

Nuxt는 애플리케이션의 선택된 페이지를 빌드 시 렌더링할 수 있도록 지원합니다. Nuxt는 요청 시마다 페이지를 동적으로 생성하는 대신, 미리 빌드된 페이지를 제공합니다.

Read more in Nuxt 렌더링 모드.

크롤 기반 프리렌더링

nuxt generate 명령어를 사용하여 Nitro 크롤러로 애플리케이션을 빌드하고 프리렌더링할 수 있습니다. 이 명령어는 nitro.static 옵션이 true로 설정된 nuxt build와 유사하며, 또는 nuxt build --prerender를 실행하는 것과 같습니다.

이 명령어는 사이트를 빌드하고, nuxt 인스턴스를 실행한 뒤, 기본적으로 루트 페이지 /와 사이트에서 해당 페이지로 연결된 모든 페이지, 그리고 그 페이지에서 또 연결된 모든 페이지를 프리렌더링합니다.

npx nuxt generate

이제 .output/public 디렉터리를 어떤 정적 호스팅 서비스에도 배포할 수 있으며, npx serve .output/public으로 로컬에서 미리보기할 수 있습니다.

Nitro 크롤러의 동작 방식:

  1. 애플리케이션의 루트 경로(/), ~/pages 디렉터리 내의 비동적 페이지, 그리고 nitro.prerender.routes 배열에 있는 기타 경로의 HTML을 로드합니다.
  2. HTML과 payload.json을 ~/.output/public/ 디렉터리에 저장하여 정적으로 서비스할 수 있도록 합니다.
  3. HTML 내의 모든 앵커 태그(<a href="...">)를 찾아 다른 경로로 이동합니다.
  4. 더 이상 크롤링할 앵커 태그가 없을 때까지 1~3단계를 각 앵커 태그에 대해 반복합니다.

이는 연결된 페이지가 아닌, 발견 가능한 페이지에 연결되어 있지 않은 페이지는 자동으로 프리렌더링할 수 없으므로 중요합니다.

nuxt generate 명령어에 대해 더 알아보기.

선택적 프리렌더링

빌드 중 Nitro가 가져와서 프리렌더링할 경로를 수동으로 지정하거나, 프리렌더링하지 않을 경로(/dynamic 등)를 nuxt.config 파일에서 무시할 수 있습니다:

nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    prerender: {
      routes: ["/user/1", "/user/2"],
      ignore: ["/dynamic"],
    },
  },
});

크롤러가 발견할 수 없는 /sitemap.xml이나 /robots.txt와 같은 경로를 프리렌더링하려면 crawlLinks 옵션과 결합할 수 있습니다:

nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    prerender: {
      crawlLinks: true,
      routes: ["/sitemap.xml", "/robots.txt"],
    },
  },
});

nitro.prerender를 true로 설정하는 것은 nitro.prerender.crawlLinks를 true로 설정하는 것과 유사합니다.

Nitro 문서에서 프리렌더링에 대해 더 알아보기.

마지막으로, routeRules를 사용하여 수동으로 구성할 수도 있습니다.

nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    // prerender를 true로 설정하여 프리렌더링되도록 구성
    "/rss.xml": { prerender: true },
    // false로 설정하여 프리렌더링에서 제외
    "/this-DOES-NOT-get-prerendered": { prerender: false },
    // /blog 하위의 모든 경로는
    // 다른 페이지에서 연결되어 있다면 프리렌더링됨
    "/blog/**": { prerender: true },
  },
});
Nitro의 routeRules 구성에 대해 더 알아보기.

간단하게, defineRouteRules를 사용하여 페이지 파일에서 직접 구성할 수도 있습니다.

이 기능은 실험적이며 사용하려면 nuxt.config에서 experimental.inlineRouteRules 옵션을 활성화해야 합니다.
pages/index.vue
<script setup>
// 또는 페이지 레벨에서 설정
defineRouteRules({
  prerender: true,
});
</script>

<template>
  <div>
    <h1>홈페이지</h1>
    <p>빌드 시 프리렌더링됨</p>
  </div>
</template>

이것은 다음과 같이 변환됩니다:

nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    "/": { prerender: true },
  },
});

런타임 프리렌더 구성

prerenderRoutes

Nuxt 컨텍스트 내에서 런타임에 Nitro가 프리렌더링할 추가 경로를 등록할 수 있습니다.

pages/index.vue
<script setup>
prerenderRoutes(["/some/other/url"]);
prerenderRoutes("/api/content/article/my-article");
</script>

<template>
  <div>
    <h1>프리렌더링 시 다른 경로도 등록됩니다</h1>
  </div>
</template>
Read more in prerenderRoutes.

prerender:routes Nuxt 훅

프리렌더링 전에 추가 경로를 등록하기 위해 호출됩니다.

nuxt.config.ts
export default defineNuxtConfig({
  hooks: {
    async "prerender:routes"(ctx) {
      const { pages } = await fetch("https://api.some-cms.com/pages").then(
        (res) => res.json(),
      );
      for (const page of pages) {
        ctx.routes.add(`/${page.name}`);
      }
    },
  },
});

prerender:generate Nitro 훅

프리렌더링 중 각 경로에 대해 호출됩니다. 프리렌더링되는 각 경로를 세밀하게 제어할 때 사용할 수 있습니다.

nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    hooks: {
      "prerender:generate"(route) {
        if (route.route?.includes("private")) {
          route.skip = true;
        }
      },
    },
  },
});