@astrojs/ vercel

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

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

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

왜 Astro Vercel인가?

섹션 제목: 왜 Astro Vercel인가?

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

설치

섹션 제목: 설치

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

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

npm

npx astro add vercel

pnpm

pnpm astro add vercel

Yarn

yarn astro add vercel

수동 설치

섹션 제목: 수동 설치

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

npm

npm install @astrojs/vercel

pnpm

pnpm add @astrojs/vercel

Yarn

yarn add @astrojs/vercel

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

astro.config.mjs

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

섹션 제목: webAnalytics

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

Added in: @astrojs/vercel@3.8.0

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

astro.config.mjs

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

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

imagesConfig

섹션 제목: imagesConfig

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

Added in: @astrojs/vercel@3.3.0

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

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

astro.config.mjs

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

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

imageService

섹션 제목: imageService

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

Added in: @astrojs/vercel@3.3.0

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

astro.config.mjs

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

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

src/pages/index.astro

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

섹션 제목: devImageService

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

Added in: @astrojs/vercel@3.8.0

기본값: ‘sharp’

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

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

astro.config.mjs

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

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

includeFiles

섹션 제목: includeFiles

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

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

astro.config.mjs

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

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

excludeFiles

섹션 제목: excludeFiles

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

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

astro.config.mjs

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

섹션 제목: maxDuration

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

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

astro.config.mjs

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 플랜이 프로젝트의 경로 수에 비해 부족한 경우 배포 중 오류 메시지를 받게 됩니다.

astro.config.mjs

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

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

Vercel 에지 미들웨어

섹션 제목: Vercel 에지 미들웨어

Vercel 에지 미들웨어를 사용하여 요청을 가로채고 응답을 보내기 전에 리디렉션할 수 있습니다. Vercel 미들웨어는 에지, SSR, 정적 배포를 위해 실행할 수 있습니다. 미들웨어용으로 이 패키지를 설치할 필요가 없을 수도 있습니다. @vercel/edge는 위치정보와 같은 일부 미들웨어 기능을 사용하는 데에만 필요합니다. 자세한 정보는 Vercel의 미들웨어 문서를 참조하세요.

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

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);
}

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

주의

rewrite를 시도하시나요? 현재 미들웨어를 사용한 요청 rewrite는 정적 파일에만 작동합니다.

Astro 미들웨어를 사용하는 Vercel 에지 미들웨어

섹션 제목: Astro 미들웨어를 사용하는 Vercel 에지 미들웨어

@astrojs/vercel/serverless 어댑터는 코드 베이스의 Astro 미들웨어에서 Vercel 에지 미들웨어를 자동으로 생성할 수 있습니다.

이는 선택적 기능이며, edgeMiddleware 옵션을 true로 설정해야 합니다.

astro.config.mjs

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 패키지가 필요합니다.

src/vercel-edge-middleware.js

/**
 *
 * @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를 사용하는 경우, 다음과 같이 함수에 타입을 제공할 수 있습니다.

src/vercel-edge-middleware.ts

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 버전 지원

섹션 제목: Node.js 버전 지원

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

Vercel 문서를 참조하여 자세히 알아보십시오.

더 많은 통합

UI 프레임워크

• 

  @astrojs/alpinejs

• 

  @astrojs/lit

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

SSR 어댑터

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

기타 통합

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap

• 

  @astrojs/tailwind