컨텐츠로 건너뛰기

@astrojs/ node

v8.2.5 GitHub npm Changelog

이 어댑터를 사용하면 Astro가 hybrid 또는 server 렌더링 사이트를 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.* 파일이 한 번에 적절하게 변경됩니다.

Terminal window
npx astro add node

수동 설치

섹션 제목: 수동 설치

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

Terminal window
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는 옵션을 어댑터 함수에 전달하여 구성할 수 있습니다. 다음 옵션을 사용할 수 있습니다.

모드

섹션 제목: 모드

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

  • middleware 모드를 사용하면 빌드된 출력을 Express.js 또는 Fastify와 같은 다른 Node.js 서버의 미들웨어로 사용할 수 있습니다.

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

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

  • standalone 모드는 항목 모듈이 실행되면서 자동으로 시작되는 서버에 빌드됩니다. 이를 통해 추가 코드 없이 빌드를 호스트에 더 쉽게 배포할 수 있습니다.

사용하기

섹션 제목: 사용하기

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

미들웨어

섹션 제목: 미들웨어

서버 엔트리포인트는 기본적으로 ./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에 빌드됩니다. 다음을 사용하여 실행할 수 있습니다.

Terminal window
node ./dist/server/entry.mjs

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

사용자 정의 호스트 및 포트

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

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

Terminal window
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에서 이를 전달하는 방법은 다음과 같습니다.

Terminal window
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)에 옮겨 저장하세요. 다음 명령을 사용하여 빌드를 시작합니다.

Terminal window
export $(cat .env.runtime) && astro build

자산

섹션 제목: 자산

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

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

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

더 많은 통합

UI 프레임워크

SSR 어댑터

기타 통합