@astrojs/ vercel

Astro는 이 어댑터를 사용하여 hybrid 또는 server 방식으로 렌더링된 사이트를 Vercel에 배포할 수 있게 해줍니다.

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

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

왜 Astro Vercel인가?

Vercel은 GitHub 저장소에 직접 연결하여 사이트를 호스팅할 수 있게 해주는 배포 플랫폼입니다. 이 어댑터는 Vercel을 통해 배포할 프로젝트를 준비하기 위해 Astro 빌드 프로세스를 향상시킵니다.

설치

Astro는 공식 통합을 설정을 자동화하기 위한 astro add 명령을 포함하고 있습니다. 원한다면, 수동으로 통합 설치할 수도 있습니다.

Astro 프로젝트의 SSR을 활성화하기 위해 다음 astro add 명령을 사용하여 Vercel 어댑터를 추가하세요. 이를 통해 @astrojs/vercel이 설치되고 astro.config.mjs 파일이 한번에 적절히 변경됩니다.

npx astro add vercel

pnpm astro add vercel

yarn astro add vercel

수동 설치

먼저, 선호하는 패키지 관리자를 사용하여 프로젝트의 종속성에 @astrojs/vercel 어댑터를 추가합니다.

npm install @astrojs/vercel

pnpm add @astrojs/vercel

yarn add @astrojs/vercel

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

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

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

대상 선택하기

다양한 대상에 배포할 수 있습니다.

serverless: Node.js 함수에서 SSR을 수행합니다.
static: Vercel의 출력 형식, 리디렉션 등을 따르는 정적 웹사이트를 생성합니다.

대상을 변경하려면 import를 변경하세요.

import vercel from '@astrojs/vercel/serverless';
import vercel from '@astrojs/vercel/static';

사용

Vercel에 프로젝트를 배포하는 방법에 대해 자세히 알아보세요.

CLI (vercel deploy)를 사용하여 배포하거나, Vercel 대시보드에서 새 레포지토리를 연결하여 배포할 수 있습니다. 또는 로컬에서 프로덕션 빌드를 생성할 수 있습니다.

astro build
vercel deploy --prebuilt

구성

이 어댑터를 구성하려면, astro.config.mjs 파일의 vercel() 함수 호출에 객체를 전달하세요.

webAnalytics

타입: VercelWebAnalyticsConfig
사용 가능한 모드: Serverless, Static

Added in: @astrojs/vercel@3.8.0

webAnalytics: { enabled: true }를 설정하여 Vercel 웹 분석을 활성화할 수 있습니다. 이렇게 하면 Vercel의 추적 스크립트가 모든 페이지에 삽입됩니다.

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

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    webAnalytics: {
      enabled: true,
    },
  }),
});

`imagesConfig`

타입: VercelImageConfig
사용 가능한 모드: Serverless, Static

Added in: @astrojs/vercel@3.3.0

Vercel의 이미지 최적화 API에 대한 구성 옵션입니다. 지원되는 매개변수의 전체 목록은 대한 구성 옵션입니다. 지원되는 모든 매개변수에 대해서는 Vercel의 이미지 구성 문서를 참조하세요.

domains 및 remotePatterns 속성은 Astro의 해당 image 설정을 통해 자동으로 채워집니다.

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

export default defineConfig({
  // ...
  output: 'static',
  adapter: vercel({
    imagesConfig: {
      sizes: [320, 640, 1280],
    },
  }),
});

`imageService`

타입: boolean
사용 가능한 모드: Serverless, Static

Added in: @astrojs/vercel@3.3.0

활성화되면 Vercel 이미지 최적화 API에 의해 구동되는 이미지 서비스가 자동으로 구성되고 프로덕션에서 사용됩니다. 개발 모드에서는 devImageService에 지정된 이미지 서비스가 대신 사용됩니다.

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

export default defineConfig({
  // ...
  output: 'static',
  adapter: vercel({
    imageService: true,
  }),
});

---
import { Image } from 'astro:assets';
import astroLogo from '../assets/logo.png';
---

<!-- 이 컴포넌트는 -->
<Image src={astroLogo} alt="My super logo!" />

<!-- 다음 과 같은 HTML이 될 것입니다 -->
<img
  src="/_vercel/image?url=_astro/logo.hash.png&w=...&q=..."
  alt="My super logo!"
  loading="lazy"
  decoding="async"
  width="..."
  height="..."
/>

`devImageService`

타입: 'sharp' | 'squoosh' | string
사용 가능한 모드: Serverless, Static

Added in: @astrojs/vercel@3.8.0

기본값: sharp

imageService가 활성화된 경우 개발모드에서 사용할 이미지 서비스를 구성할 수 있습니다. 이는 개발 기기에 Sharp의 종속성을 설치할 수는 없는 경우 Squoosh와 같은 다른 이미지 서비스를 사용하여 개발 환경에서 이미지를 미리 볼 수 있으므로 유용할 수 있습니다. 빌드는 영향을 받지 않고 항상 Vercel의 이미지 최적화를 사용합니다.

Astro의 내장 서비스 대신 사용자 정의 이미지 서비스를 사용하기 위해 임의의 값으로 설정할 수도 있습니다.

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

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    imageService: true,
    devImageService: 'squoosh',
  }),
});

`isr`

타입: boolean | VercelISRConfig
사용 가능한 모드: Serverless

Added in: @astrojs/vercel@7.2.0

기본값: false

첫 번째 요청 후 사전 렌더링된 페이지와 동일한 방식으로 주문형 렌더링된 페이지를 캐시하는 ISR (증분 정적 재생성) 함수로 프로젝트를 배포할 수 있습니다.

이 기능을 활성화하려면 astro.config.mjs 파일의 Vercel 어댑터 구성에서 isr을 true로 설정하세요.

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

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

ISR 함수 요청에는 정적 모드의 요청과 유사한 검색 매개변수가 포함되지 않습니다.

ISR 캐시 무효화

기본적으로 ISR 함수는 배포 기간 동안 캐시됩니다. 만료 시간을 설정하거나 캐싱에서 특정 경로를 완전히 제외하여 캐싱을 추가로 제어할 수 있습니다.

시간 기반 무효화

expiration 값을 초 단위로 구성하여 경로를 캐시하는 시간을 변경할 수 있습니다.

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

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    isr: {
      // 첫 번째 요청 시 모든 페이지를 캐시하고 1일 동안 저장합니다.
      expiration: 60 * 60 * 24,
    },
  }),
});

캐싱에서 경로 제외

Vercel의 초안 모드 또는 주문형 증분형 정적 재생성 (ISR)을 구현하려면 bypass 토큰을 생성하고 이를 캐싱에서 제외할 경로와 함께 isr 구성에 제공할 수 있습니다.

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

export default defineConfig({
  output: 'server',
  adapter: vercel({
    isr: {
      // 여러분이 생성하는 무작위 비밀 문자열입니다.
      bypassToken: '005556d774a8',
      // 항상 최신 상태로 제공되는 경로입니다.
      exclude: ['/api/invalidate'],
    },
  }),
});

`includeFiles`

타입: string[]
사용 가능한 모드: Serverless

파일을 함수와 번들링하기 위해 이 속성을 사용합니다. 이는 누락된 파일을 발견했을 때 유용합니다.

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

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    includeFiles: ['./my-data.json'],
  }),
});

`excludeFiles`

타입: string[]
사용 가능한 모드: Serverless

이 속성을 사용하면 포함된 파일을 번들링 프로세스에서 제외할 수 있습니다.

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

export default defineConfig({
  // ...
  output: 'server',
  adapter: vercel({
    excludeFiles: ['./src/some_big_file.jpg'],
  }),
});

`maxDuration`

타입: number
사용 가능한 모드: Serverless

이 속성을 사용하여 서버리스 함수가 타임아웃되기 전에 실행될 수 있는 최대 시간(초)을 연장하거나 제한할 수 있습니다. 계정 플랜의 기본 및 최대 한도는 Vercel 문서를 참조하세요.

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

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

함수 번들링 구성

Vercel 어댑터는 기본적으로 모든 경로를 단일 함수로 결합합니다.

functionPerRoute 옵션을 사용하여 빌드를 각 경로에 대한 개별 함수로 나눌 수 있습니다. 이렇게 하면 각 함수의 크기가 줄어들어 개별 함수의 크기 제한을 초과할 가능성이 줄어듭니다. 또한, 코드 시작이 더 빠릅니다.

functionPerRoute를 활성화하기 전에 Vercel 플랜이 적절한 수의 함수를 포함하고 있는지 확인하세요. 예를 들어, Vercel의 무료 등급은 각 배포를 12개 이하의 함수로 제한합니다. Vercel 플랜이 프로젝트의 경로 수에 비해 부족한 경우 배포 중 오류 메시지를 받게 됩니다.

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

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

Vercel 에지 미들웨어

Vercel 에지 미들웨어를 사용하여 요청을 가로채고 응답을 보내기 전에 리디렉션할 수 있습니다. Vercel 미들웨어는 에지, SSR, 정적 배포에서 실행할 수 있습니다.

미들웨어용으로 이 패키지를 설치할 필요가 없을 수도 있습니다. @vercel/edge는 위치정보와 같은 일부 미들웨어 기능을 사용하는 데에만 필요합니다. 자세한 내용은 Vercel의 미들웨어 문서를 참조하세요.

프로젝트의 루트에 middleware.js 파일을 추가하세요.

export const config = {
  // 미들웨어는 /admin 경로에서만 실행됩니다
  matcher: '/admin',
};

export default function middleware(request) {
  const url = new URL(request.url);
  // 여기서 IP 위치나 쿠키를 검색할 수 있습니다.
  if (url.pathname === '/admin') {
    url.pathname = '/';
  }
  return Response.redirect(url);
}

로컬에서 개발하는 동안, 미들웨어를 실행하기 위해 vercel dev를 실행할 수 있습니다. 프로덕션에서는 Vercel이 이를 처리합니다.

Vercel Edge Functions에서 Astro 미들웨어 실행

@astrojs/vercel/serverless 어댑터는 코드 베이스의 Astro 미들웨어에서 에지 함수를 생성할 수 있습니다. edgeMiddleware가 활성화되면 에지 함수는 정적 자산, 사전 렌더링된 페이지, 주문형 렌더링된 페이지를 포함한 모든 요청에 대해 미들웨어 코드를 실행합니다.

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

이는 선택적 기능입니다. 활성화하려면 edgeMiddleware를 true로 설정하세요.

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

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

선택적으로, Astro.locals를 생성하기 위해 srcDir 폴더에 어댑터가 인식할 수 있는 vercel-edge-middleware.(js|ts)라는 이름을 가진 파일을 만들수있습니다.

타입을 구성하기 위해서는 @vercel/edge 패키지가 필요합니다.

/**
 *
 * @param options.request {Request}
 * @param options.context {import("@vercel/edge").RequestContext}
 * @returns {object}
 */
export default function ({ request, context }) {
  // 요청 및 컨텍스트로 작업을 수행합니다
  return {
    title: "Spider-man's blog",
  };
}

TypeScript를 사용하는 경우, 다음과 같이 함수에 타입을 제공할 수 있습니다.

import type { RequestContext } from '@vercel/edge';

export default function ({ request, context }: { request: Request; context: RequestContext }) {
  // 요청 및 컨텍스트로 작업을 수행합니다
  return {
    title: "Spider-man's blog",
  };
}

이 함수에서 반환된 데이터는 Astro 미들웨어로 전달됩니다.

이 함수는

default 함수를 내보내야 합니다;
object를 return해야 합니다;
request 및 context 속성을 가진 객체를 인자로 전달받습니다;
request는 Request로 타입이 지정됩니다;
context는 RequestContext로 타입이 지정됩니다;

한계 및 제약

이 기능을 선택할 때 주의해야 할 몇 가지 제약 사항이 있습니다.

Vercel 에지 미들웨어는 항상 Request를 수신하는 첫 번째 함수이며 Response를 수신하는 마지막 함수입니다. 이는 Vercel이 설정한 경계를 따르는 설계적 제약입니다.
Astro.locals 객체를 생성하기 위해서는 request 및 context만 사용할 수 있습니다. 리디렉션 등의 작업은 Astro 미들웨어에 위임해야 합니다.
Astro.locals는 직렬화 가능해야 합니다. 그렇지 않으면 런타임 오류가 발생합니다. 이는 Map, function, Set 등의 복잡한 유형을 저장할 수 없음을 의미합니다.

Node.js 버전 지원

@astrojs/vercel 어댑터는 Astro 프로젝트를 Vercel에 배포하기 위한 특정 Node.js 버전을 지원합니다. Vercel에서 지원하는 Node.js 버전을 보려면 프로젝트의 Settings 탭을 클릭하고 “Node.js Version” 섹션까지 아래로 스크롤하세요.