컨텐츠로 건너뛰기

@astrojs/ node

v9.2.0 GitHub npm 변경 로그

이 어댑터를 사용하면 Astro가 요청 시 렌더링되는 라우트를 Node 대상에 배포할 수 있습니다.

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

왜 Astro Node.js인가?

섹션 제목: 왜 Astro Node.js인가?

Node.js는 서버 측 코드를 위한 JavaScript 런타임입니다. @astrojs/node는 standalone 모드에서 사용하거나 Express와 같은 다른 http 서버의 미들웨어로 사용할 수 있습니다.

설치

섹션 제목: 설치

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

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

터미널 창
npx astro add node

수동 설치

섹션 제목: 수동 설치

먼저, 선호하는 패키지 관리자를 사용하여 프로젝트의 종속성에 Node 어댑터를 추가하세요.

터미널 창
npm install @astrojs/node

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

astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';


export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone',
  }),
});

구성

섹션 제목: 구성

@astrojs/node는 옵션을 어댑터 함수에 전달하여 구성할 수 있습니다. 다음 옵션을 사용할 수 있습니다.

mode

섹션 제목: mode

타입: 'middleware' | 'standalone'

어댑터가 middleware 또는 standalone 모드로 빌드되는지 여부를 제어합니다.

  • middleware 모드를 사용하면 빌드된 출력을 Express.js 또는 Fastify와 같은 다른 Node.js 서버의 미들웨어로 사용할 수 있습니다.
  • standalone 모드는 진입점 모듈이 실행될 때 자동으로 시작되는 서버를 빌드합니다. 이를 통해 추가 코드 없이 빌드 결과를 호스트에 더 쉽게 배포할 수 있습니다.
astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';


export default defineConfig({
  adapter: node({
    mode: 'middleware',
  }),
});

사용하기

섹션 제목: 사용하기

먼저 빌드를 수행합니다. 선택한 모드 (위 참조)에 따라 아래의 적절한 단계를 따르세요.

미들웨어

섹션 제목: 미들웨어

서버 엔트리포인트는 기본적으로 ./dist/server/entry.mjs에 빌드됩니다. 이 모듈은 Node request 및 response 객체를 지원하는 모든 프레임워크와 함께 사용할 수 있는 handler 함수를 내보냅니다.

예를 들어 Express의 경우:

run-server.mjs
import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';


const app = express();
// astro.config.mjs 파일의 `base` 옵션에 따라 이를 변경하세요.
// 일치해야 합니다. 기본값은 "/"입니다.
const base = '/';
app.use(base, express.static('dist/client/'));
app.use(ssrHandler);


app.listen(8080);

또는 Fastify (>4)를 사용하면 다음과 같습니다.

run-server.mjs
import Fastify from 'fastify';
import fastifyMiddie from '@fastify/middie';
import fastifyStatic from '@fastify/static';
import { fileURLToPath } from 'node:url';
import { handler as ssrHandler } from './dist/server/entry.mjs';


const app = Fastify({ logger: true });


await app
  .register(fastifyStatic, {
    root: fileURLToPath(new URL('./dist/client', import.meta.url)),
  })
  .register(fastifyMiddie);
app.use(ssrHandler);


app.listen({ port: 8080 });

또한 Astro.locals 또는 Astro 미들웨어를 통해 액세스할 객체를 전달할 수도 있습니다.

run-server.mjs
import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';


const app = express();
app.use(express.static('dist/client/'));
app.use((req, res, next) => {
  const locals = {
    title: 'New title',
  };


  ssrHandler(req, res, next, locals);
});


app.listen(8080);

미들웨어 모드는 파일 제공을 수행하지 않습니다. 이를 수행하려면 HTTP 프레임워크를 구성해야 합니다. 기본적으로 클라이언트 자산은 ./dist/client/에 기록됩니다.

Standalone

섹션 제목: Standalone

standalone 모드에서는 서버 엔트리포인트가 실행될 때 서버가 시작됩니다. 기본적으로 ./dist/server/entry.mjs에 빌드됩니다. 다음을 사용하여 실행할 수 있습니다.

터미널 창
node ./dist/server/entry.mjs

standalone 모드의 경우 서버는 페이지 및 API 경로 외에도 파일 제공을 처리합니다.

사용자 정의 호스트 및 포트

섹션 제목: 사용자 정의 호스트 및 포트

런타임 시 환경 변수로 전달하여 standalone 서버가 실행되는 호스트와 포트를 재정의할 수 있습니다.

터미널 창
HOST=0.0.0.0 PORT=4321 node ./dist/server/entry.mjs

HTTPS

섹션 제목: HTTPS

기본적으로 standalone 서버는 HTTP를 사용합니다. 이는 HTTPS를 수행하는 프록시 서버가 앞에 있는 경우에 잘 작동합니다. HTTPS 자체를 실행하기 위해 standalone 서버가 필요한 경우 SSL 키와 인증서를 제공해야 합니다.

환경 변수 SERVER_CERT_PATH 및 SERVER_KEY_PATH를 통해 키 및 인증 경로를 전달할 수 있습니다. Bash에서 이를 전달하는 방법은 다음과 같습니다.

터미널 창
SERVER_KEY_PATH=./private/key.pem SERVER_CERT_PATH=./private/cert.pem node ./dist/server/entry.mjs

런타임 환경 변수

섹션 제목: 런타임 환경 변수

빌드 프로세스가 실행될 때 환경 변수가 포함된 .env 파일이 존재하는 경우 이러한 값은 정적 웹 사이트를 생성할 때와 마찬가지로 출력에 하드 코딩됩니다.

빌드하는 동안 런타임 변수는 .env 파일에 없어야 하며 런타임에 예상되는 모든 환경 변수를 Astro에 제공해야 합니다. (VARIABLE_1=placeholder astro build) 이는 빌드된 애플리케이션이 실행될 때 실제 값을 사용할 수 있다는 신호를 Astro에 보냅니다. placeholder 값은 빌드 프로세스에서 무시되며 Astro는 런타임에 제공된 값을 사용합니다.

런타임 변수가 여러 개인 경우 .env 파일에서 별도의 파일 (예: .env.runtime)에 옮겨 저장하세요. 다음 명령을 사용하여 빌드를 시작합니다.

터미널 창
export $(cat .env.runtime) && astro build

자산

섹션 제목: 자산

standalone 모드에서는 dist/client/ 폴더의 자산이 standalone 서버를 통해 제공됩니다. 이러한 자산을 CDN에 배포할 수 있으며, 이 경우 서버는 실제로 해당 자산을 제공하지 않습니다. 그러나 인트라넷 사이트와 같은 일부 경우에는 애플리케이션 서버에서 직접 정적 자산을 제공하는 것이 좋습니다.

dist/client/_astro/ 폴더에 있는 자산은 Astro가 빌드한 자산입니다. 이러한 자산은 모두 해시로 이름이 지정되므로 긴 캐시 헤더가 제공될 수 있습니다. 내부적으로 어댑터는 다음 자산에 대해 이 헤더를 추가합니다.

Cache-Control: public, max-age=31536000, immutable

세션

섹션 제목: 세션

Astro 세션 API를 사용하면 요청 간에 사용자 데이터를 쉽게 저장할 수 있습니다. 이는 사용자 데이터 및 설정, 쇼핑 카트, 인증 자격 증명 등에 활용될 수 있습니다. 쿠키 저장소와 달리 데이터 크기에 제한이 없으며, 다른 기기에서도 복원할 수도 있습니다.

Node 어댑터를 사용하는 경우 Astro는 세션 스토리지를 위해 로컬 파일 시스템을 사용합니다. 다른 세션 스토리지 드라이버를 사용하려면 Astro 구성에서 지정할 수 있습니다. 자세한 내용은 session 구성 참조를 확인하세요.

더 많은 통합

UI 프레임워크

SSR 어댑터

기타 통합

기여하기 커뮤니티 후원하기