@astrojs/ netlify

이 어댑터를 사용하면 Astro가 hybrid 또는 server 렌더링된 사이트를 Netlify에 배포할 수 있습니다.

Astro를 정적 사이트 빌더 로 사용하는 경우 어댑터가 필요하지 않습니다.

Netlify 배포 가이드에서 Astro 사이트를 배포하는 방법을 알아보세요.

왜 Astro Netlify인가?

Netlify는 GitHub 저장소에 직접 연결하여 사이트를 호스팅할 수 있는 배포 플랫폼입니다. 이 어댑터는 Astro 빌드 프로세스를 향상시켜 Netlify를 통한 배포용 프로젝트를 준비합니다.

설치

Astro에는 공식 통합 설정을 자동화하는 astro add 명령이 포함되어 있습니다. 원하는 경우 대신 통합을 수동으로 설치할 수 있습니다.

astro add 명령을 사용하여 Astro 프로젝트에서 SSR을 활성화하려면 Netlify 어댑터를 추가하세요. 그러면 @astrojs/netlify가 설치되고 astro.config.mjs 파일이 한 번에 적절하게 변경됩니다.

npx astro add netlify

pnpm astro add netlify

yarn astro add netlify

수동 설치

먼저, 선호하는 패키지 관리자를 사용하여 프로젝트 종속성에 Netlify 어댑터를 설치합니다.

npm install @astrojs/netlify

pnpm add @astrojs/netlify

yarn add @astrojs/netlify

그런 다음 어댑터와 원하는 주문형 렌더링 모드를 astro.config.* 파일에 추가하세요.

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  output: 'server',
  adapter: netlify(),
});

사용하기

여기에서 전체 배포 가이드를 읽어보세요.

지침에 따라 사이트를 로컬로 빌드하세요. 빌드 후에는 .netlify/functions-internal/ 폴더의 Netlify Functions과 .netlify/edge-functions/ 폴더의 Netlify Edge Functions을 모두 포함하는 .netlify/ 폴더가 생성됩니다.

사이트를 배포하려면 Netlify CLI를 설치하고 다음을 실행하세요.

netlify deploy

Astro의 Netlify 블로그 게시물과 Netlify 문서는 이 통합을 사용하여 Netlify에 배포하는 방법에 대한 자세한 정보를 제공합니다.

사이트에서 에지 컨텍스트에 액세스하기

Netlify Edge Functions는 사용자 IP, 지리적 위치 데이터, 쿠키 등 요청에 대한 메타데이터를 포함하는 컨텍스트 객체를 제공합니다.

이는 Astro.locals.netlify.context 객체를 통해 액세스할 수 있습니다.

---
const {
  geo: { city },
} = Astro.locals.netlify.context;
---

<h1>Hello there, friendly visitor from {city}!</h1>

TypeScript를 사용하는 경우 NetlifyLocals를 사용하도록 src/env.d.ts를 업데이트하여 적절한 타입을 얻을 수 있습니다.

/// <reference path="../.astro/types.d.ts" />

type NetlifyLocals = import('@astrojs/netlify').NetlifyLocals;

declare namespace App {
  interface Locals extends NetlifyLocals {
    // ...
  }
}

사전 렌더링된 페이지에서는 사용할 수 없습니다.

Edge Functions에서 Astro 미들웨어 실행

모든 Astro 미들웨어는 빌드 시 사전 렌더링된 페이지에 적용되고 런타임 시 주문형 렌더링 페이지에 적용됩니다.

사전 렌더링된 페이지에 대한 리디렉션, 액세스 제어 또는 사용자 정의 응답 헤더를 구현하려면 edgeMiddleware 옵션을 활성화하여 Netlify Edge Functions에서 미들웨어를 실행하세요.

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  output: 'server',
  adapter: netlify({
    edgeMiddleware: true,
  }),
});

edgeMiddleware가 활성화되면 에지 함수는 정적 자산, 사전 렌더링된 페이지, 주문형 렌더링된 페이지를 포함한 모든 요청에 대해 미들웨어 코드를 실행합니다.

주문형 렌더링된 페이지의 경우 context.locals 객체는 JSON을 사용하여 직렬화되어 렌더링을 수행하는 서버리스 함수의 헤더로 전송됩니다. 보안 조치로서 서버리스 함수는 생성된 에지 함수에서 발생하지 않는 한 403 Forbidden 응답이 포함된 요청 처리를 거부합니다.

Netlify 이미지 CDN 지원

이 어댑터는 기본적으로 Netlify Image CDN을 사용하여 빌드 시간에 영향을 주지 않고 즉시 이미지를 변환합니다. 내부적으로는 Astro 이미지 서비스를 사용하여 구현됩니다.

Netlify의 Image CDN 원격 이미지 최적화를 선택 해제하려면 imageCDN 옵션을 사용하세요.

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  output: 'server',
  adapter: netlify({
    imageCDN: false,
  }),
});

다른 도메인에서 호스팅되는 이미지를 사용하는 경우 image.domains 또는 image.remotePatterns 구성 옵션을 사용하여 도메인 또는 URL 패턴을 승인해야 합니다.

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
    // ...
    output: 'server',
    adapter: netlify(),
    image: {
      domains: ['example.com'],
    },
});

자세한 내용은 원격 이미지 승인 가이드를 참조하세요. 여러분의 사이트와 동일한 도메인에 호스팅된 이미지에는 필요하지 않습니다.

Netlify 어댑터를 사용하는 정적 사이트

Netlify에서 호스팅되는 정적 사이트 (output: 'static')의 경우 일반적으로 어댑터가 필요하지 않습니다. 그러나 일부 배포 기능은 어댑터를 통해서만 사용할 수 있습니다.

Netlify의 이미지 서비스를 사용하고 구성하려면 정적 사이트에서 이 어댑터를 설치해야 합니다.

Astro 구성에서 redirects 구성을 사용하는 경우 Netlify 어댑터를 사용하여 이를 적절한 _redirects 형식으로 변환할 수 있습니다.

import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  // ...
  adapter: netlify(),
  redirects: {
    '/blog/old-post': '/blog/new-post',
  },
});

astro build를 실행하면 dist/_redirects 파일이 생성됩니다. Netlify는 이를 사용하여 프로덕션에서 페이지를 적절하게 라우팅합니다.

캐싱 페이지

동적 콘텐츠가 없는 주문형 렌더링 페이지를 캐시하여 성능을 향상하고 리소스 사용량을 줄일 수 있습니다. 어댑터에서 cacheOnDemandPages 옵션을 활성화하면 서버에서 렌더링된 모든 페이지를 최대 1년 동안 캐시합니다.

export default defineConfig({
  // ...
  output: 'server',
  adapter: netlify({
    cacheOnDemandPages: true,
  }),
});

응답에 캐싱 헤더를 추가하여 페이지별로 변경할 수 있습니다.

---
import Layout from '../components/Layout.astro';

Astro.response.headers.set('CDN-Cache-Control', 'public, max-age=45, must-revalidate');
---

<Layout title="Astro on Netlify">
  {new Date()}
</Layout>

세밀한 캐시 제어를 통해 Netlify는 CDN-Cache-Control 또는 Vary와 같은 표준 캐싱 헤더를 지원합니다. time to live (TTL) 또는 stale while revalidate (SWR) 캐싱 등의 구현에 대해 알아보기 위해 문서를 참조하세요: https://docs.netlify.com/platform/caching