구성 참조

다음 참조는 Astro에서 지원되는 모든 구성 옵션을 다룹니다. Astro 구성에 대해 자세히 알아보려면 Astro 구성 안내서를 읽어보세요.

import { defineConfig } from 'astro/config';

export default defineConfig({
  // 구성 옵션은 여기에 작성합니다...
});

최상위 옵션

site

타입: string

배포된 최종 URL입니다. Astro는 이 전체 URL을 사용하여 최종 빌드에서 사이트맵과 표준 URL을 생성합니다. Astro를 최대한 활용하려면 이 구성을 설정하는 것이 좋습니다.

{
  site: 'https://www.my-site.dev';
}

base

타입: string

배포할 기본 경로입니다. Astro는 개발 및 프로덕션 빌드 모두에서 이 경로를 페이지 및 자산의 루트로 사용합니다.

아래 예에서 astro dev는 /docs에서 서버를 시작합니다.

{
  base: '/docs';
}

이 옵션을 사용할 때 모든 정적 자산 가져오기 및 URL은 base를 접두사로 추가해야 합니다. import.meta.env.BASE_URL을 통해 이 값에 액세스할 수 있습니다.

import.meta.env.BASE_URL의 값은 base에 어떤 값을 설정했는지에 관계없이 trailingSlash 구성에 의해 결정됩니다.

trailingSlash: "always"가 설정된 경우 후행 슬래시가 항상 포함됩니다. trailingSlash: "never"가 설정된 경우 base에 슬래시가 포함되어 있더라도 BASE_URL에는 후행 슬래시가 포함되지 않습니다.

또한 Astro는 통합에 사용할 수 있도록 하기 전에 config.base의 구성된 값을 내부적으로 조작합니다. 통합에서 읽은 config.base 값도 동일한 방식으로 trailingSlash 구성에 따라 결정됩니다.

아래 예시에서, import.meta.env.BASE_URL 및 config.base 값은 모두 /docs가 됩니다.

{
   base: '/docs/',
   trailingSlash: "never"
}

아래 예시에서 import.meta.env.BASE_URL 및 config.base 값은 모두 /docs/가 됩니다.

{
   base: '/docs',
   trailingSlash: "always"
}

trailingSlash

타입: 'always' | 'never' | 'ignore'
기본값: 'ignore'

개발 서버의 경로 일치 동작을 설정합니다. 다음 옵션 중에서 선택하세요.

'always' - 후행 슬래시가 포함된 URL만 일치시킵니다. (예: “/foo/“)
'never' - 후행 슬래시가 포함된 URL은 절대 일치시키지 않습니다. (예: “/foo”)
'ignore' - 후행 ”/” 존재 여부에 관계없이 URL을 일치시킵니다.

프로덕션 호스트에서 후행 슬래시 작동 여부를 엄격하게 처리하는 경우 이 구성 옵션을 사용하세요.

또한 개발 중에 슬래시가 있거나 없는 URL이 작동하지 않도록 더 엄격하게 설정하려는 경우 이를 설정할 수도 있습니다.

{
  // 예: 개발 중에 후행 슬래시가 필요합니다.
  trailingSlash: 'always';
}

참고하기:

build.format

redirects

타입: Record.<string, RedirectConfig>
기본값: {}

Added in: astro@2.9.0

키는 일치시킬 경로이고 값은 리디렉션할 경로인 리디렉션 매핑을 지정합니다.

정적 경로와 동적 경로를 모두 리디렉션할 수 있지만 동일한 종류의 경로로만 리디렉션할 수 있습니다. 예를 들어 '/article': '/blog/[...slug]' 리디렉션을 사용할 수 없습니다.

{
  redirects: {
    '/old': '/new',
    '/blog/[...slug]': '/articles/[...slug]',
  }
}

어댑터가 설치되지 않은 정적으로 생성된 사이트의 경우 <meta http-equiv="refresh"> 태그를 사용하여 클라이언트 리디렉션을 생성하며 상태 코드는 지원하지 않습니다.

output: static 모드에서 SSR을 사용하거나 정적 어댑터를 사용하는 경우 상태 코드가 지원됩니다. Astro는 301 상태로 리디렉션된 GET 요청을 처리하고 다른 요청 방법에는 308 상태를 사용합니다.

리디렉션 구성의 객체를 사용하여 리디렉션 상태 코드를 맞춤설정할 수 있습니다.

{
  redirects: {
    '/other': {
      status: 302,
      destination: '/place',
    },
  }
}

output

타입: 'static' | 'server' | 'hybrid'
기본값: 'static'

빌드의 출력 대상을 지정합니다.

'static' - 모든 정적 호스트에 배포될 정적 사이트를 구축합니다.
'server' - SSR (서버 측 렌더링)을 지원하는 호스트에 배포할 앱을 구축합니다.
'hybrid' - 몇 개의 서버 측 렌더링 페이지가 포함된 정적 사이트를 구축합니다.

import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static',
});

참고하기:

adapter

adapter

타입: AstroIntegration

빌드 어댑터를 사용하여 선호하는 서버, 서버리스, 에지 호스트에 배포하세요. Astro SSR을 사용하려면 Netlify, Vercel 등을 위한 자사 어댑터 중 하나를 가져오세요.

SSR에 대한 자세한 내용은 서버 측 렌더링 안내서를 참조하고, 전체 호스트 목록은 배포 안내서를 참조하세요.

import netlify from '@astrojs/netlify';
{
  // 예: Netlify 서버리스 배포를 위한 빌드
  adapter: netlify(),
}

참고하기:

output

integrations

맞춤형 통합으로 Astro를 확장하세요. 통합은 프레임워크 지원 (Solid.js 등), 새로운 기능 (사이트맵 등), 새 라이브러리(Partytown 등)를 한번에 추가하는 것을 도와줍니다.

Astro 통합을 시작하는 데 도움이 필요하면 통합 안내서를 읽어보세요.

import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';
{
  // 예: Astro에 React + Tailwind 지원 추가
  integrations: [react(), tailwind()];
}

root

타입: string
CLI: --root
기본값: "." (현재 작업 디렉터리)

프로젝트 루트 디렉터리가 아닌 디렉터리에서 astro CLI 명령을 실행하는 경우에만 이 옵션을 제공해야 합니다. 일반적으로 이 옵션은 Astro 구성 파일 대신 CLI를 통해 제공됩니다. Astro가 구성 파일을 찾으려면 먼저 프로젝트 루트를 알아야 하기 때문입니다.

상대 경로를 제공하는 경우 (예: --root: './my-project') Astro는 현재 작업 디렉터리를 기준으로 경로를 확인합니다.

예

{
  root: './my-project-directory';
}

$ astro build --root ./my-project-directory

srcDir

타입: string
기본값: "./src"

Astro가 여러분의 사이트를 읽을 디렉터리를 설정하세요.

값은 절대 파일 시스템 경로이거나 프로젝트 루트에 대한 상대 경로일 수 있습니다.

{
  srcDir: './www';
}

publicDir

타입: string
기본값: "./public"

정적 자산의 디렉터리를 설정합니다. 이 디렉터리의 파일은 개발 중에 /에 제공되고 빌드 중에 build 디렉터리에 복사됩니다. 이러한 파일은 변환이나 번들링 없이 항상 있는 그대로 제공되거나 복사됩니다.

값은 절대 파일 시스템 경로이거나 프로젝트 루트에 대한 상대 경로일 수 있습니다.

{
  publicDir: './my-custom-publicDir-directory';
}

outDir

타입: string
기본값: "./dist"

astro build가 최종 빌드를 작성하는 디렉터리를 설정합니다.

값은 절대 파일 시스템 경로이거나 프로젝트 루트에 대한 상대 경로일 수 있습니다.

{
  outDir: './my-custom-build-directory';
}

참고하기:

build.server

cacheDir

타입: string
기본값: "./node_modules/.astro"

빌드 아티팩트를 캐싱하기 위한 디렉터리를 설정합니다. 이 디렉터리의 파일은 빌드 시간을 단축하기 위해 후속 빌드에서 사용됩니다.

값은 절대 파일 시스템 경로이거나 프로젝트 루트에 대한 상대 경로일 수 있습니다.

{
  cacheDir: './my-custom-cache-directory';
}

compressHTML

타입: boolean
기본값: true

이는 HTML 출력을 최소화하고 HTML 파일의 크기를 줄이는 옵션입니다.

기본적으로 Astro는 .astro 컴포넌트에서 줄 바꿈을 포함하여 HTML의 공백을 무손실 방식으로 제거합니다. HTML의 시각적 렌더링을 유지하기 위해 필요에 따라 일부 공백이 유지될 수 있습니다. 이는 개발 모드와 최종 빌드 모두에서 발생합니다.

HTML 압축을 비활성화하려면 compressHTML을 false로 설정하세요.

{
  compressHTML: false;
}

scopedStyleStrategy

타입: 'where' | 'class' | 'attribute'
기본값: 'attribute'

Added in: astro@2.4

Astro 컴포넌트에서 스타일 범위 지정에 사용되는 전략을 지정합니다. 다음 중에서 선택하세요:

'where' - :where 선택자를 사용하면 구체성이 증가하지 않습니다.
'class' - 클래스 기반 선택기를 사용하면 구체성이 +1 증가합니다.
'attribute' - data- 속성을 사용하면 구체성이 +1 증가합니다.

Astro 컴포넌트의 요소 선택기가 전역 스타일 기본값 (예: 전역 스타일시트)을 재정의하도록 하려는 경우 'class'를 사용하는 것이 도움이 됩니다. “where’를 사용하면 구체성을 더 잘 제어할 수 있지만, 적용되는 선택기를 제어하려면 더 높은 구체성 선택기, 레이어 및 기타 도구를 사용해야 합니다. ‘attribute’를 사용하는 것은 요소의 class` 속성을 조작하고 자신의 스타일 지정 로직과 Astro의 스타일 적용 사이의 충돌을 피해야 할 때 유용합니다.

security

타입: boolean
기본값: {}

Added in: astro@4.9.0

Astro 웹사이트에 대한 보안 조치를 활성화합니다.

이러한 기능은 server 모드를 사용하여 요청 시 렌더링된 페이지 (SSR) 또는 hybrid 모드에서 사전 렌더링을 선택 해제한 페이지에만 존재합니다.

export default defineConfig({
  output: "server",
  security: {
    checkOrigin: true
  }
})

security.checkOrigin

타입: boolean
기본값: ‘false’

Added in: astro@4.9.0

활성화되면 모든 최신 브라우저에서 자동으로 전달되는 “origin” 헤더가 각 Request에서 보낸 URL과 일치하는지 확인합니다. 이는 CSRF (Cross-Site Request Forgery) 보호를 위해 사용됩니다.

“origin” 확인은 요청 시 렌더링된 페이지에 대해서만 실행되며, content-type 헤더가 'application/x-www-form-urlencoded', 'multipart/form-data', 'text/plain' 중 하나인 POST, PATCH, DELETE, PUT 요청에 대해서만 실행됩니다.

“origin” 헤더가 요청의 pathname과 일치하지 않으면 Astro는 403 상태 코드를 반환하며 페이지를 렌더링하지 않습니다.

vite

타입: ViteUserConfig

추가 구성 옵션을 Vite에 전달합니다. Astro가 필요할 수 있는 일부 고급 구성을 지원하지 않을 때 유용합니다.

vitejs.dev에서 전체 vite 구성 객체 문서를 확인하세요.

예

{
  vite: {
    ssr: {
      // 예: 필요한 경우, 손상된 패키지가 SSR 처리를 건너뛰도록 강제합니다.
      external: ['broken-npm-package'],
    }
  }
}

{
  vite: {
    // 예: Astro 프로젝트에 직접 맞춤형 vite 플러그인 추가
    plugins: [myPlugin()],
  }
}

빌드 옵션

build.format

타입: ('file' | 'directory' | 'preserve')
기본값: 'directory'

각 페이지의 출력 파일 형식을 제어합니다. 이 값은 어댑터에 의해 설정될 수 있습니다.

'file': Astro는 각 페이지 경로에 대해 이름이 지정된 HTML 파일을 생성합니다. (예를 들어 src/pages/about.astro와 src/pages/about/index.astro는 모두 /about.html 파일을 빌드합니다)
'directory': Astro는 각 페이지에 대해 중첩된 index.html 파일이 있는 디렉터리를 생성합니다. (예를 들어 src/pages/about.astro와 src/pages/about/index.astro는 모두 /about/index.html 파일을 빌드합니다)
'preserve': Astro는 소스 폴더에 나타나는 HTML 파일을 정확하게 생성합니다. (예를 들어 src/pages/about.astro는 /about.html을 빌드하고 src/pages/about/index.astro는 /about/index.html 파일을 빌드합니다.)

{
  build: {
    // 예: 빌드 중에 `page/index.html` 대신 `page.html`을 생성합니다.
    format: 'file';
  }
}

Astro.url에 미치는 영향

build.format을 설정하면 빌드 중에 Astro.url이 무엇으로 설정될지 제어할 수 있습니다.

directory - Astro.url.pathname에는 폴더 동작을 모방하기 위해 후행 슬래시가 포함됩니다. 즉 /foo/입니다.
file - Astro.url.pathname에는 .html이 포함됩니다. 즉 /foo.html입니다.

이는 new URL('./relative', Astro.url)을 사용하여 상대 URL을 생성할 때 개발과 빌드 간에 일관된 동작을 얻게 된다는 것을 의미합니다.

개발에서 후행 슬래시 동작의 불일치를 방지하려면 빌드 형식에 따라 trailingSlash 옵션을 'always' 또는 'never'로 제한할 수 있습니다.

directory - trailingSlash: 'always'로 설정됩니다.
file - trailingSlash: 'never'로 설정됩니다.

build.client

타입: string
기본값: './dist/client'

output: 'server' 또는 output: 'hybrid'인 경우에만 클라이언트측 CSS 및 JavaScript의 출력 디렉터리를 제어합니다. outDir은 코드가 빌드되는 위치를 제어합니다.

이 값은 outDir을 기준으로 합니다.

{
  output: 'server', // 또는 'hybrid'
  build: {
    client: './client'
  }
}

build.server

타입: string
기본값: './dist/server'

SSR로 빌드할 때 서버 JavaScript의 출력 디렉터리를 제어합니다.

이 값은 outDir을 기준으로 합니다.

{
  build: {
    server: './server';
  }
}

build.assets

타입: string
기본값: '_astro'

Added in: astro@2.0.0

Astro에서 생성된 자산 (예: JS 및 CSS 번들)이 있어야 하는 빌드 출력의 디렉터리를 지정합니다.

{
  build: {
    assets: '_custom';
  }
}

참고하기:

outDir

build.assetsPrefix

타입: string | Record.<string, string>
기본값: undefined

Added in: astro@2.2.0

Astro에서 생성된 자산 링크의 접두사를 지정합니다. 자산이 현재 사이트와 다른 도메인에서 제공되는 경우 사용할 수 있습니다.

이를 위해서는 로컬 ./dist/_astro 폴더의 자산을 원격 도메인의 해당 /_astro/ 폴더에 업로드해야 합니다.

_astro 경로의 이름을 바꾸려면 build.assets에 새 디렉터리를 지정합니다.

동일한 도메인 (예: https://cdn.example.com/_astro/...)에 업로드된 모든 자산을 가져오려면 assetsPrefix를 루트 도메인의 문자열로 설정합니다. (base 구성에 관계없이):

{
  build: {
    assetsPrefix: 'https://cdn.example.com';
  }
}

추가: astro@4.5.0

또한 assetsPrefix에 객체를 전달하여 각 파일 형식에 대해 서로 다른 도메인을 지정할 수도 있습니다. 이 경우 fallback 속성이 필요하며 기본적으로 다른 파일에 사용됩니다.

{
  build: {
    assetsPrefix: {
      'js': 'https://js.cdn.example.com',
      'mjs': 'https://js.cdn.example.com',
      'css': 'https://css.cdn.example.com',
      'fallback': 'https://cdn.example.com'
    }
  }
}

build.serverEntry

타입: string
기본값: 'entry.mjs'

SSR로 빌드할 때 서버 엔트리포인트의 파일 이름을 지정합니다. 이 엔트리포인트는 일반적으로 배포하려는 호스트에 따라 달라지며 어댑터에 의해 설정됩니다.

런타임에서 파일이 JavaScript 모듈임을 감지할 수 있도록 이 파일은 .mjs로 끝나는 것이 좋습니다.

{
  build: {
    serverEntry: 'main.mjs';
  }
}

build.redirects

타입: boolean
기본값: true

Added in: astro@2.6.0

빌드 중에 리디렉션을 HTML로 출력할지 여부를 지정합니다. 이 옵션은 output: 'static' 모드에만 적용됩니다. SSR 리디렉션에서는 모든 응답과 동일하게 처리됩니다.

이 옵션은 주로 리디렉션을 위한 특수 구성 파일이 있고 HTML 기반 리디렉션이 필요하지 않거나 필요하지 않은 어댑터에서 사용하기 위한 것입니다.

{
  build: {
    redirects: false;
  }
}

build.inlineStylesheets

타입: 'always' | 'auto' | 'never'
기본값: auto

Added in: astro@2.6.0

프로젝트 스타일을 별도의 CSS 파일로 브라우저에 보낼지 <style> 태그에 인라인할지 제어합니다. 다음 옵션 중에서 선택하세요.

'always' - 프로젝트 스타일은 <style> 태그에 인라인됩니다.
'auto' - ViteConfig.build.assetsInlineLimit (기본값: 4kb)보다 작은 스타일시트만 인라인됩니다. 그렇지 않으면 프로젝트 스타일이 외부 스타일시트로 전송됩니다.
'never' - 프로젝트 스타일은 외부 스타일시트로 전송됩니다.

{
  build: {
    inlineStylesheets: `never`,
  },
}

서버 옵션

astro dev와 astro preview 모두에서 사용되는 Astro 개발 서버를 사용자 정의하세요.

{
  server: { port: 1234, host: true}
}

실행 명령 (“dev”, “preview”)을 기반으로 다른 구성을 설정하려면 이 구성 옵션에 함수를 전달할 수도 있습니다.

{
  // 예: 함수 구문을 사용하여 명령에 따라 사용자 정의
  server: ({ command }) => ({ port: command === 'dev' ? 4321 : 4000 });
}

server.host

타입: string | boolean
기본값: false

Added in: astro@0.24.0

서버가 수신해야 하는 네트워크 IP 주소 (예: 로컬 호스트가 아닌 IP)를 설정합니다.

false - 네트워크 IP 주소를 노출하지 않습니다.
true - LAN 및 공용 주소를 포함한 모든 주소에서 수신합니다.
[custom-address] - [custom-address] (예: 192.168.0.1)의 네트워크 IP 주소를 노출합니다.

server.port

타입: number
기본값: 4321

서버가 수신해야 하는 포트를 설정합니다.

주어진 포트가 이미 사용 중이라면 Astro는 자동으로 다음 사용 가능한 포트를 시도합니다.

{
  server: {
    port: 8080;
  }
}

server.open

타입: string | boolean
기본값: false

Added in: astro@2.1.8

시작 시 개발 서버가 브라우저 창에서 열릴지 여부를 제어합니다.

열려는 URL을 지정하려면 전체 URL 문자열 (예: ”http://example.com”) 또는 경로 이름 (예: “/about”)을 전달하세요.

{
  server: {
    open: '/about';
  }
}

server.headers

타입: OutgoingHttpHeaders
기본값: {}

Added in: astro@1.7.0

astro dev 및 astro preview에서 전송되도록 사용자 정의 HTTP 응답 헤더를 설정합니다.

개발 툴바 옵션

devToolbar.enabled

타입: boolean
기본값: true

Astro 개발 툴바를 활성화할지 여부입니다. 이 툴바를 사용하면 페이지 아일랜드를 검사하고 성능 및 접근성에 대한 유용한 정보를 볼 수 있습니다.

이 옵션은 전체 프로젝트로 범위가 지정되며, 자신에 대해서만 툴바를 비활성화하려면 npm run astro preferences disable devToolbar를 실행하세요. 모든 Astro 프로젝트에 대한 툴바를 비활성화하려면 npm run astro preferences disable devToolbar --global을 실행하세요.

프리페치 옵션

타입: boolean | object

더 빠른 페이지 전환을 제공하려면 사이트의 링크에 대해 프리페치를 활성화하세요. (<ViewTransitions /> 라우터를 사용하는 페이지에서는 기본적으로 활성화됩니다. 이 동작을 선택하지 않으려면 prefetch: false를 설정하세요.)

이 구성은 프로젝트의 모든 페이지에 프리페치 스크립트를 자동으로 추가하여 data-astro-prefetch 속성에 대한 액세스를 제공합니다. 해당 페이지에 대한 프리페칭을 활성화하려면 페이지의 <a /> 링크에 이 속성을 추가하세요.

<a href="/about" data-astro-prefetch>About</a>

prefetch.defaultStrategy 및 prefetch.prefetchAll 옵션을 사용하여 기본 프리페치 동작을 추가로 사용자 정의하세요.

자세한 내용은 프리페치 안내서를 참조하세요.

prefetch.prefetchAll

타입: boolean

data-astro-prefetch 속성이 없는 링크를 포함하여 모든 링크에 대해 프리페치를 활성화합니다. <ViewTransitions /> 라우터를 사용할 때 이 값의 기본값은 true입니다. 그렇지 않은 경우 기본값은 false입니다.

prefetch: {
  prefetchAll: true;
}

true로 설정하면 개별 링크에 data-astro-prefetch="false"를 설정하여 프리페치를 개별적으로 비활성화할 수 있습니다.

<a href="/about" data-astro-prefetch="false">About</a>

prefetch.defaultStrategy

타입: 'tap' | 'hover' | 'viewport' | 'load'
기본값: 'hover'

data-astro-prefetch 속성이 없는 링크에 설정된 경우 사용할 기본 프리페치 전략입니다.

'tap': 링크를 클릭하기 직전에 미리 가져옵니다.
'hover': 링크 위로 마우스를 가져가거나 링크에 초점을 맞추면 미리 가져옵니다. (기본값)
'viewport': 링크가 뷰포트에 들어갈 때 미리 가져옵니다.
'load': 페이지가 로드된 후 페이지의 모든 링크를 미리 가져옵니다.

속성에 값을 설정하여 이 기본값을 무시하고 개별 링크에 대해 다른 전략을 선택할 수 있습니다.

<a href="/about" data-astro-prefetch="viewport">About</a>

이미지 옵션

image.endpoint

타입: string
기본값: undefined

Added in: astro@3.1.0

개발 및 SSR에서 이미지 최적화에 사용할 엔드포인트를 설정합니다. 기본 엔드포인트를 사용하려면 undefined로 설정하세요.

엔드포인트는 항상 /_image에 삽입됩니다.

{
  image: {
    // 예: 사용자 정의 이미지 엔드포인트 사용
    endpoint: './src/image-endpoint.ts',
  },
}

image.service

타입: Object
기본값: {entrypoint: 'astro/assets/services/sharp', config?: {}}

Added in: astro@2.1.0

Astro의 자산 지원에 사용되는 이미지 서비스를 설정합니다.

값은 이미지 서비스가 사용할 엔트리포인트가 있는 객체여야 하며 선택적으로 서비스에 전달할 구성 객체여야 합니다.

서비스 엔트리포인트는 포함된 서비스 중 하나이거나 타사 패키지일 수 있습니다.

{
  image: {
    // 예: 사용자 정의 구성으로 Sharp 기반 이미지 서비스 활성화
    service: {
       entrypoint: 'astro/assets/services/sharp',
       config: {
         limitInputPixels: false,
      },
     },
  },
}

image.service.config.limitInputPixels

타입: boolean
기본값: true

Added in: astro@4.1.0

Sharp 이미지 서비스가 처리할 이미지 크기를 제한할지 여부입니다.

Sharp 이미지 서비스의 기본 이미지 크기 제한을 우회하고 큰 이미지를 처리하려면 false를 설정하세요.

image.domains

타입: Array.<string>
기본값: {domains: []}

Added in: astro@2.10.10

원격 이미지 최적화를 위해 허용되는 이미지 소스 도메인 목록을 정의합니다. 다른 원격 이미지는 Astro에서 최적화되지 않습니다.

이 옵션에는 개별 도메인 이름의 배열이 문자열로 필요합니다. 와일드카드는 허용되지 않습니다. 대신 image.remotePatterns를 사용하여 허용되는 소스 URL 패턴 목록을 정의하세요.

{
  image: {
    // 예: 단일 도메인에서 원격 이미지 최적화 허용
    domains: ['astro.build'],
  },
}

image.remotePatterns

타입: Array.<RemotePattern>
기본값: {remotePatterns: []}

Added in: astro@2.10.10

원격 이미지 최적화를 위해 허용되는 이미지 소스 URL 패턴 목록을 정의합니다.

remotePatterns는 네 가지 속성으로 구성할 수 있습니다.

protocol
hostname
port
pathname

{
  image: {
    // 예: aws s3 버킷의 모든 이미지 처리를 허용합니다.
    remotePatterns: [{
      protocol: 'https',
      hostname: '**.amazonaws.com',
    }],
  },
}

아래 설명과 같이 와일드카드를 사용하여 허용되는 hostname 및 pathname 값을 정의할 수 있습니다. 그렇지 않으면 제공된 정확한 값만 구성됩니다.

hostname:

’**’ 로 시작하면 모든 하위 도메인 (‘endsWith’)을 허용합니다.
’*’ 로 시작하면 한 수준의 하위 도메인만 허용합니다.

pathname:

모든 하위 경로 (‘startsWith’)를 허용하려면 ’/**’ 로 끝납니다.
한 수준의 하위 경로만 허용하려면 ’/*’ 로 끝납니다.

Markdown 옵션

markdown.shikiConfig

타입: Partial<ShikiConfig>

Shiki 구성 옵션. 사용법은 Markdown 구성 문서를 참조하세요.

markdown.syntaxHighlight

타입: 'shiki' | 'prism' | false
기본값: shiki

사용할 구문 강조 표시 (있는 경우)

shiki - Shiki를 사용합니다.
prism - Prism을 사용합니다.
false - 구문 강조를 적용하지 않습니다.

{
  markdown: {
    // 예: Markdown에서 구문 강조를 위해 Prism을 사용하도록 전환
    syntaxHighlight: 'prism',
  }
}

markdown.remarkPlugins

타입: RemarkPlugins

remark 플러그인을 전달하여 Markdown 빌드 방법을 맞춤설정하세요. 플러그인 기능을 가져와 적용하거나 (권장) 플러그인 이름을 문자열로 전달할 수 있습니다.

import remarkToc from 'remark-toc';
{
  markdown: {
    remarkPlugins: [ [remarkToc, { heading: "contents"} ] ]
  }
}

markdown.rehypePlugins

타입: RehypePlugins

rehype 플러그인을 전달하여 Markdown의 출력 HTML이 처리되는 방식을 맞춤설정하세요. 플러그인 기능을 가져와 적용하거나 (권장) 플러그인 이름을 문자열로 전달할 수 있습니다.

import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';
{
  markdown: {
    rehypePlugins: [rehypeAccessibleEmojis];
  }
}

markdown.gfm

타입: boolean
기본값: true

Added in: astro@2.0.0

Astro는 기본적으로 GitHub 기반 Markdown을 사용합니다. 이를 비활성화하려면 gfm 플래그를 false로 설정하세요.

{
  markdown: {
    gfm: false,
  }
}

markdown.smartypants

타입: boolean
기본값: true

Added in: astro@2.0.0

Astro는 기본적으로 SmartyPants 포매터를 사용합니다. 이를 비활성화하려면 smartypants 플래그를 false로 설정하세요.

{
  markdown: {
    smartypants: false,
  }
}

markdown.remarkRehype

타입: RemarkRehype

옵션을 remark-rehype에 전달하세요.

{
  markdown: {
    // 예: 각주 텍스트를 다른 언어로 번역합니다. 기본 영어 값은 다음과 같습니다.
    remarkRehype: { footnoteLabel: "Footnotes", footnoteBackLabel: "Back to reference 1"},
  },
};

i18n

타입: object

Added in: astro@3.5.0

i18n 라우팅을 구성하고 일부 맞춤 옵션을 지정할 수 있습니다.

Astro의 국제화에 대한 자세한 내용은 안내서를 참조하세요.

i18n.defaultLocale

타입: string

Added in: astro@3.5.0

웹사이트/애플리케이션의 기본 언어입니다. 필수 필드입니다.

특정 언어 형식이나 구문이 적용되지는 않지만 호환성을 극대화하려면 필요에 따라 소문자와 하이픈 (예: “es”, “pt-br”)을 사용하는 것이 좋습니다.

i18n.locales

타입: Locales

Added in: astro@3.5.0

defaultLocale을 포함하여 웹사이트에서 지원하는 모든 언어의 목록입니다. 필수 필드입니다.

언어는 개별 코드 (예: ['en', 'es', 'pt-br'])로 나열되거나 공유된 코드 path (예: { path: "english", codes: ["en", "en-US"]})에 매핑될 수 있습니다. 이 코드는 배포된 사이트의 URL 구조를 결정하는 데 사용됩니다.

특정 언어 코드 형식이나 구문은 적용되지 않지만 콘텐츠 파일이 포함된 프로젝트 폴더는 목록의 locales 항목과 정확히 일치해야 합니다. 맞춤 URL 경로 접두사를 가리키는 여러 codes가 있는 경우 구성된 path와 동일한 이름을 가진 폴더에 콘텐츠 파일을 저장하세요.

i18n.fallback

타입: Record.<string, string>

Added in: astro@3.5.0

존재하지 않는 페이지로 이동할 때의 대체 전략 (예: 번역된 페이지가 생성되지 않음)

이 객체를 사용하여 지원하는 각 언어에 대한 대체 locale 경로를 선언하세요. 대체가 지정되지 않으면 사용할 수 없는 페이지는 404를 반환합니다.

예

다음 예시는 /pt-br/에서 사용할 수 없는 페이지를 es 버전으로 리디렉션하고, /fr/에서 사용할 수 없는 페이지를 en 버전으로 리디렉션하도록 콘텐츠 대체 전략을 구성합니다. 사용할 수 없는 /es/ 페이지는 404를 반환합니다.

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr', 'pt-br', 'es'],
    fallback: {
      pt: 'es',
      fr: 'en',
    },
  },
});

i18n.routing

타입: Routing

Added in: astro@3.7.0

사이트 URL을 결정하기 위한 라우팅 전략을 제어합니다. 기본 언어에 대한 폴더/URL 경로 구성을 기반으로 이를 설정합니다.

i18n.routing.prefixDefaultLocale

타입: boolean
기본값: false

Added in: astro@3.7.0

false인 경우 기본이 아닌 언어에만 언어 접두사가 표시됩니다. defaultLocale은 언어 접두사를 표시하지 않으며, 콘텐츠 파일은 현지화된 폴더에 존재하지 않습니다. URL은 기본이 아닌 모든 언어의 경우 example.com/[locale]/content/ 형식이지만 기본 언어의 경우 example.com/content/ 형식입니다.

true인 경우 모든 URL에 언어 접두사가 표시됩니다. URL은 기본 언어를 포함하여 모든 경로에 대해 example.com/[locale]/content/ 형식입니다. 현지화된 폴더는 기본값을 포함하여 모든 언어에 사용됩니다.

export default defineConfig({
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
    routing: {
      prefixDefaultLocale: true,
    }
  }
})

i18n.routing.redirectToDefaultLocale

타입: boolean
기본값: true

Added in: astro@4.2.0

prefixDefaultLocale: true가 설정된 경우 src/pages/index.astro에 의해 생성된 홈 URL (/)이 /[defaultLocale]로 리디렉션되는지 여부를 구성합니다.

사이트 루트에서 자동 리디렉션을 비활성화하려면 redirectToDefaultLocale: false를 설정하세요.

export default defineConfig({
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr'],
    routing: {
      prefixDefaultLocale: true,
      redirectToDefaultLocale: false,
    },
  },
});

i18n.routing.manual

타입: string

Added in: astro@4.6.0

이 옵션이 활성화되면 Astro는 사용자 정의 로직을 구현할 수 있도록 i18n 미들웨어를 비활성화합니다. 다른 routing 옵션 (예: prefixDefaultLocale)은 routing: "manual"으로 구성할 수 없습니다.

여러분은 자신만의 라우팅 로직을 작성하거나 Astro의 i18n 미들웨어를 수동으로 실행할 책임이 있습니다.

export default defineConfig({
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
    routing: {
      prefixDefaultLocale: true,
    }
  }
})

Legacy 플래그

일부 사용자가 Astro 버전 간에 마이그레이션할 수 있도록 돕기 위해 때때로 legacy 플래그를 도입합니다. 이러한 플래그를 사용하면 최신 버전에서 더 이상 사용되지 않거나 오래된 Astro의 동작을 선택할 수 있으므로 계속 업그레이드하고 새로운 Astro 릴리스를 활용할 수 있습니다.

Experimental 플래그

Astro는 사용자가 새로운 기능에 조기에 액세스할 수 있도록 experimental 플래그를 제공합니다. 이러한 플래그는 안정성이 보장되지 않습니다.

experimental.directRenderScript

타입: boolean
기본값: false

Added in: astro@4.5.0

스크립트가 사용되지 않는 페이지에서 스크립트가 실행되는 것을 방지하기 위해 보다 안정적인 전략을 가능하게 합니다.

스크립트는 Astro 파일에 선언된 대로 직접 렌더링됩니다. (TypeScript, node_modules 가져오기, 중복 제거 스크립트 등 기존 기능 포함) 이제 Astro 파일에서 조건부로 스크립트를 렌더링할 수도 있습니다. 그러나 이는 스크립트가 더 이상 <head>로 끌어올려지지 않으며 페이지의 여러 스크립트가 더 이상 번들링되지 않음을 의미합니다. 이 옵션을 활성화하면 모든 <script> 태그가 예상대로 작동하는지 확인해야 합니다.

이 옵션은 Astro 4.5.0에서 기본적으로 활성화됩니다.

{
  experimental: {
    directRenderScript: true,
  },
}

experimental.actions

타입: boolean
기본값: false

Added in: astro@4.8.0

액션은 어디에서나 호출할 수 있는 타입 안정성을 갖춘 백엔드 함수를 작성하는 데 도움이 됩니다. output 속성을 사용하여 서버 렌더링을 활성화하고 experimental 객체에 actions 플래그를 추가합니다.

{
  output: 'hybrid', // 또는 'server'
  experimental: {
    actions: true,
  },
}

src/actions/index.ts 파일에서 모든 액션을 선언합니다. 이 파일은 전역 액션 핸들러입니다.

astro:actions 모듈의 defineAction() 유틸리티를 사용하여 액션을 정의합니다. 이 액션은 서버 측 요청 핸들러를 정의하기 위해 handler 속성을 허용합니다. 액션이 인수를 허용하는 경우 input 속성을 적용하여 Zod로 매개변수를 검증하세요.

이 예시에서는 like와 comment라는 두 가지 액션을 정의합니다. like 액션은 postId 문자열이 포함된 JSON 객체를 허용하는 반면, comment 액션은 postId, author 및 body 문자열을 포함하는 FormData를 허용합니다. 각 handler는 데이터베이스를 업데이트하고 타입 안정성을 갖춘 응답을 반환합니다.

import { defineAction, z } from "astro:actions";

export const server = {
  like: defineAction({
    input: z.object({ postId: z.string() }),
    handler: async ({ postId }) => {
      // db에서 likes 업데이트

      return likes;
    },
  }),
  comment: defineAction({
    accept: 'form',
    input: z.object({
      postId: z.string(),
      author: z.string(),
      body: z.string(),
    }),
    handler: async ({ postId }) => {
      // db에 comment 삽입

      return comment;
    },
  }),
};

그런 다음 astro:actions의 actions 객체를 사용하여 클라이언트 컴포넌트에서 액션을 호출합니다. JSON을 사용할 때는 타입 안정성을 갖춘 객체를 전달할 수 있고, 액션 정의에서 accept: 'form'을 사용할 때는 FormData 객체를 전달할 수 있습니다.

이 예시는 React 컴포넌트에서 like 및 comment 액션을 호출합니다.

import { actions } from "astro:actions";
import { useState } from "react";

export function Like({ postId }: { postId: string }) {
  const [likes, setLikes] = useState(0);
  return (
    <button
      onClick={async () => {
        const newLikes = await actions.like({ postId });
        setLikes(newLikes);
      }}
    >
      {likes} likes
    </button>
  );
}

export function Comment({ postId }: { postId: string }) {
  return (
    <form
      onSubmit={async (e) => {
        e.preventDefault();
        const formData = new FormData(e.target as HTMLFormElement);
        const result = await actions.blog.comment(formData);
        // result 핸들링
      }}
    >
      <input type="hidden" name="postId" value={postId} />
      <label htmlFor="author">Author</label>
      <input id="author" type="text" name="author" />
      <textarea rows={10} name="body"></textarea>
      <button type="submit">Post</button>
    </form>
  );
}

전체 개요를 확인하고 이 실험적 API에 대한 피드백을 제공하려면 Actions RFC를 참조하세요.

experimental.contentCollectionCache

타입: boolean
기본값: false

Added in: astro@3.5.0

정적 모드에서 빌드할 때 콘텐츠 컬렉션에 대한 영구 캐시를 활성화합니다.

{
  experimental: {
    contentCollectionCache: true,
  },
}

experimental.clientPrerender

타입: boolean
기본값: false

Added in: astro@4.2.0

지원되는 브라우저의 클라이언트에서 미리 가져온 페이지를 사전 렌더링할 수 있습니다.

이 기능은 실험적인 Speculation Rules Web API를 사용하여 기본 prefetch 동작을 전역적으로 향상시켜 클라이언트에서 링크를 사전 렌더링합니다. 이 기능을 활성화하기 전에 클라이언트에서 사전 렌더링할 때 발생할 수 있는 위험을 검토하는 것이 좋습니다.

원하는 prefetch 구성 옵션과 함께 astro.config.mjs 파일에서 클라이언트 측 사전 렌더링을 활성화하세요.

{
  prefetch: {
    prefetchAll: true,
    defaultStrategy: 'viewport',
  },
  experimental: {
    clientPrerender: true,
  },
}

프리페치를 선택하려면 사이트의 <a /> 링크에서 data-astro-prefetch 속성을 계속 사용하세요. 문서 헤드에 <link> 태그를 추가하거나 JavaScript로 페이지를 가져오는 대신 <script> 태그에 해당 speculation rules이 추가됩니다.

클라이언트 측 사전 렌더링에는 브라우저 지원이 필요합니다. Speculation Rules API가 지원되지 않는 경우 prefetch는 지원되는 전략으로 대체됩니다.

더 많은 prefetch 옵션 및 사용법은 프리페치 가이드를 참조하세요.

experimental.globalRoutePriority

타입: boolean
기본값: false

Added in: astro@4.2.0

모든 경로에 대해 동일한 경로 우선 순위 규칙을 따라 파일 기반 프로젝트 경로와 함께 리디렉션 및 삽입된 경로의 우선 순위를 동일하게 지정합니다.

이를 통해 특정 유형의 경로에 자동으로 우선순위를 지정하지 않음으로써 프로젝트의 경로를 보다 효과적으로 제어할 수 있으며 모든 경로에 대한 경로 우선순위 순서를 표준화합니다.

다음 예시에서는 파일 기반 경로, 삽입된 경로 및 리디렉션이 결합될 때 어떤 경로가 특정 페이지 URL을 빌드하는지 보여줍니다.

파일 기반 경로: /blog/post/[pid]
파일 기반 경로: /[page]
삽입된 경로: /blog/[...slug]
리디렉션: /blog/tags/[tag] -> /[tag]
리디렉션: /posts -> /blog

experimental.globalRoutingPriority를 활성화한 경우 (Astro 4.0 기본 경로 우선 순위 대신):

/blog/tags/astro는 /tags/[tag]로의 리디렉션에 의해 빌드됩니다. (삽입된 경로인 /blog/[...slug] 대신)
/blog/post/0은 파일 기반 경로인 /blog/post/[pid]에 의해 빌드됩니다. (삽입된 경로인 /blog/[...slug] 대신)
/posts는 /blog로의 리디렉션에 의해 빌드됩니다. (파일 기반 경로인 /[page] 대신)

경로 우선순위가 동일한 두 경로가 동일한 URL을 빌드하려고 시도하는 경로 충돌이 발생하는 경우 Astro는 충돌하는 경로를 식별하는 경고를 기록합니다.

experimental.env

타입: object
기본값: undefined

Added in: astro@4.10.0

실험적인 astro:env 기능을 활성화합니다.

astro:env API를 사용하면 환경 변수에 대해 타입 안정성을 갖춘 스키마를 구성하고 서버 또는 클라이언트에서 사용할 수 있는지 여부를 나타낼 수 있습니다. 적절한 /client 또는 /server 모듈에서 정의된 변수를 가져와 사용합니다.

---
import { API_URL } from "astro:env/client"
import { API_SECRET_TOKEN } from "astro:env/server"

const data = await fetch(`${API_URL}/users`, {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${API_SECRET_TOKEN}`
  },
  body: JSON.stringify({ appId: APP_ID, nodeEnv: NODE_ENV })
})
---

<script>
import { API_URL } from "astro:env/client"

fetch(`${API_URL}/ping`)
</script>

환경 변수의 데이터 타입과 속성을 정의하려면 experimental.env.schema Astro 구성에 스키마를 선언하세요. envField 도우미를 사용하면 변수를 문자열, 숫자 또는 부울로 정의하고 객체에 속성을 전달할 수 있습니다.

import { defineConfig, envField } from "astro/config"

export default defineConfig({
    experimental: {
        env: {
            schema: {
                API_URL: envField.string({ context: "client", access: "public", optional: true }),
                PORT: envField.number({ context: "server", access: "public", default: 4321 }),
                API_SECRET: envField.string({ context: "server", access: "secret" }),
            }
        }
    }
})

현재 지원되는 데이터 타입은 문자열, 숫자, 부울, 열거형 네 가지입니다.

env.schema에 정의된 context (클라이언트 또는 서버) 및 access(비밀 또는 공개) 설정의 조합에 따라 결정되는 세 종류의 환경 변수가 있습니다.

공개 클라이언트 변수: 이러한 변수는 최종 클라이언트 및 서버 번들 모두에 포함되며 astro:env/client 모듈을 통해 클라이언트와 서버 모두에서 액세스할 수 있습니다.
```
import { API_URL } from "astro:env/client"
```
공개 서버 변수: 이 변수는 최종 서버 번들에 포함되며 astro:env/server 모듈을 통해 서버에서 액세스할 수 있습니다.
```
import { PORT } from "astro:env/server"
```
비밀 서버 변수: 이 변수는 최종 번들의 일부가 아니며 astro:env/server 모듈을 통해 서버에서 액세스할 수 있습니다. getSecret() 도우미 함수를 사용하면 스키마에 지정되지 않은 비밀을 검색할 수 있습니다. 이 구현은 어댑터에서 제공되며, 기본값은 process.env입니다:
```
import { API_SECRET, getSecret } from "astro:env/server"

const SECRET_NOT_IN_SCHEMA = getSecret("SECRET_NOT_IN_SCHEMA") // string | undefined
```

참고: 이 데이터를 클라이언트에 보내는 안전한 방법이 없기 때문에 비밀 클라이언트 변수는 지원되지 않습니다. 따라서 스키마에서 context: "client"와 access: "secret"을 모두 구성하는 것은 불가능합니다.

전체 개요를 확인하고 이 실험적 API에 대한 피드백을 제공하려면 Astro Env RFC를 참조하세요.

experimental.env.schema

타입: EnvSchema
기본값: undefined

Added in: astro@4.10.0

envField를 사용하여 데이터 타입 (string, number, boolean)과 환경 변수의 속성 (context (클라이언트 또는 서버), access (공개 또는 비밀), default (사용할 기본값)) 및 환경 변수의 선택 사항 여부 (기본 값은 false)를 정의하는 객체입니다.

import { defineConfig, envField } from "astro/config"

export default defineConfig({
  experimental: {
    env: {
      schema: {
        API_URL: envField.string({ context: "client", access: "public", optional: true }),
        PORT: envField.number({ context: "server", access: "public", default: 4321 }),
        API_SECRET: envField.string({ context: "server", access: "secret" }),
      }
    }
  }
})

experimental.env.validateSecrets

타입: boolean
기본값: false

Added in: astro@4.11.6

개발 서버를 시작하거나 빌드를 실행할 때 서버에서 비밀의 유효성을 검사할지 여부입니다.

기본적으로 개발 서버나 빌드를 시작할 때 서버에서는 공개 변수만 검증되고, 비공개 변수는 런타임에만 검증됩니다. 이 옵션이 활성화되면 개발 서버나 빌드 시작 시 비공개 변수도 함께 검증됩니다. 이는 일부 CI (지속적 통합) 파이프라인에서 배포하기 전에 모든 비밀이 올바르게 설정되었는지 확인하는 데 유용합니다.

import { defineConfig, envField } from "astro/config"

export default defineConfig({
  experimental: {
    env: {
      schema: {
        // ...
      },
      validateSecrets: true
    }
  }
})

experimental.serverIslands

타입: boolean
기본값: false

Added in: astro@4.12.0

실험적인 서버 아일랜드 기능을 활성화합니다. 서버 아일랜드는 페이지가 이미 렌더링된 후, 비동기적으로 렌더링되도록 컴포넌트를 지연시키는 기능을 제공합니다.

활성화하려면 어댑터를 사용하여 주문형 서버 렌더링 output 모드를 구성하고 experimental 객체에 serverIslands 플래그를 추가합니다

{
  output: 'hybrid', // 또는 'server'
  adapter: nodejs({ mode: 'standalone' }),
  experimental: {
    serverIslands: true,
  },
}

Astro 컴포넌트에서 server:defer 지시어를 사용하면 초기 렌더링을 지연시킬 수 있습니다:

---
import Avatar from '~/components/Avatar.astro';
---
<Avatar server:defer />

외부 페이지는 빌드 타임 (hybrid) 또는 런타임(server)에 아일랜드 콘텐츠가 생략되고 그 자리에 <script> 태그가 포함된 상태로 렌더링됩니다.

브라우저에서 페이지가 로드된 후 스크립트 태그는 요청을 통해 아일랜드 콘텐츠로 교체됩니다.

모든 Astro 컴포넌트는 server: defer 속성을 지정하여 렌더링을 지연시킬 수 있습니다. 특별한 API는 없으며 평소처럼 .astro 코드를 작성하면 됩니다.

---
import { getUser } from '../api';
const user = await getUser(Astro.locals.userId);
---
<img class="avatar" src={user.imageUrl}>

서버 아일랜드 대체 콘텐츠

컴포넌트가 페이지의 나머지 부분과 함께 렌더링되지 않으므로 일반 콘텐츠 (예: 로딩 메시지)를 추가하여 임시로 그 자리에 표시할 수 있습니다. 이 콘텐츠는 페이지가 처음 렌더링되고 아일랜드가 로드되기 전에 나타납니다.

slot="fallback" 속성을 가진 자리 표시자 콘텐츠를 Astro 컴포넌트의 자식으로 추가합니다. 아일랜드 콘텐츠를 사용할 수 있게 되면 대체 콘텐츠가 교체됩니다.

아래 예시에서는 일반 아바타를 대체 콘텐츠로 표시한 다음, view transitions를 사용하여 개인화된 아바타로 애니메이션을 표시합니다.

<Avatar server:defer>
  <svg slot="fallback" class="generic-avatar" transition:name="avatar">...</svg>
</Avatar>

전체 개요를 보거나 이 실험적인 API에 대한 피드백을 제공하려면 서버 아일랜드 RFC를 참조하세요.

experimental.contentIntellisense

타입: boolean
기본값: false

Added in: astro@4.14.0 New

호환되는 편집기에서 콘텐츠 컬렉션 항목에 대한 Intellisense 기능 (예: 코드 완성, 빠른 힌트)을 사용하도록 설정합니다.

이 기능을 활성화하면 프로젝트의 .astro 디렉터리에 JSON 스키마가 생성되어 추가됩니다. Astro 언어 서버는 내부 콘텐츠 파일 (.md, .mdx, .mdoc)에서 Intellisense를 제공하기 위해 이러한 파일을 사용할 수 있습니다.

{
  experimental: {
    contentIntellisense: true,
  },
}

Astro VS Code 확장 프로그램에서 이 기능을 사용하려면 VS Code 설정에서 astro.content-intellisense 옵션도 활성화해야 합니다. Astro 언어 서버를 직접 사용하는 편집기에서 이 기능을 활성화하려면 contentIntellisense: true 초기화 매개 변수를 전달하세요.

experimental.contentLayer

타입: boolean
기본값: false

Added in: astro@4.14.0 New

Content Layer API는 Astro에서 콘텐츠와 데이터를 처리하는 새로운 방법입니다. 이는 콘텐츠 컬렉션과 유사하며 이를 기반으로 src/content/의 로컬 파일을 넘어 컬렉션에 loader를 추가하여 원격 API를 포함한 모든 곳에서 콘텐츠를 가져올 수 있도록 합니다.

기존 콘텐츠 컬렉션은 몇 가지 작은 변경을 통해 Content Layer API로 마이그레이션할 수 있습니다. 그러나 Content Layer API로 구동되는 새 컬렉션을 추가하기 위해 모든 컬렉션을 한 번에 업데이트할 필요는 없습니다. src/content/config.ts에 정의된 기존 API와 새 API를 동시에 사용하는 컬렉션을 가질 수 있습니다.

Content Layer API는 더욱 강력하고 성능이 뛰어나도록 설계되어 사이트가 수천 페이지로 확장할 수 있도록 지원합니다. 데이터는 빌드 간 캐시되고 점진적으로 업데이트됩니다. 비슷한 크기의 메모리 감소로 Markdown 구문 분석은 5-10배 빨라지고, MDX는 2-3배 더 빨라집니다.

활성화하려면 Astro 구성의 experimental 객체에 contentLayer 플래그를 추가하세요:

{
  experimental: {
    contentLayer: true,
  }
}

`loader`를 사용하여 데이터 가져오기

Content Layer API를 사용하면 (프로젝트에 로컬로 저장하든 원격으로 저장하든) src/content/ 폴더 외부에서 콘텐츠를 가져올 수 있으며, loader 속성을 사용하여 데이터를 검색할 수 있습니다.

loader는 컬렉션의 스키마에 정의되어 있으며 항목의 배열을 반환합니다. Astro는 로컬 콘텐츠를 가져오기 위한 두 가지 내장 로더 함수 (glob() 및 file())와 자체 로더를 구성하고 원격 데이터를 가져오기 위한 API 액세스를 제공합니다.

glob() 로더는 파일 시스템 어디에서나 Markdown, MDX, Markdoc 또는 JSON 파일 디렉터리에서 항목을 만듭니다. 일치시킬 항목 파일인 pattern과 파일이 있는 위치를 나타내는 파일 경로인 base를 인자로 전달받습니다. 항목당 파일이 하나씩 있을 때 이 옵션을 사용하세요.

file() 로더는 단일 로컬 파일에서 여러 항목을 생성합니다. 모든 항목이 객체 배열에 저장되어 있을 때 이 방법을 사용합니다.

import { defineCollection, z } from 'astro:content';
import { glob, file } from 'astro/loaders';

const blog = defineCollection({
  // 기본적으로 ID는 `base`를 기준으로
  // 파일 경로에서 생성된 슬러그입니다.
  loader: glob({ pattern: "**\/*.md", base: "./src/data/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
  })
});

const dogs = defineCollection({
  // 경로는 프로젝트 루트에 대한 상대 경로 또는 절대 경로입니다.
  loader: file("src/data/dogs.json"),
  schema: z.object({
    id: z.string(),
    breed: z.string(),
    temperament: z.array(z.string()),
  }),
});

export const collections = { blog, dogs };

Content Layer API로 쿼리 및 렌더링하기

컬렉션은 콘텐츠 컬렉션과 동일한 방식으로 쿼리할 수 있습니다:

import { getCollection, getEntry } from 'astro:content';

// 컬렉션에서 모든 항목을 가져옵니다.
// 컬렉션의 이름을 인수로 요구합니다.
const allBlogPosts = await getCollection('blog');

// 컬렉션에서 단일 항목을 가져옵니다.
// 컬렉션의 이름과 ID가 필요합니다.
const labradorData = await getEntry('dogs', 'labrador-retriever');

Markdown, MDX 또는 Markdoc에서 생성된 항목은 render() 함수를 사용하여 페이지에 직접 렌더링할 수 있습니다.

---
import { getEntry, render } from 'astro:content';

const post = await getEntry('blog', Astro.params.slug);

const { Content, headings } = await render(post);
---

<Content />

로더 만들기

Content Layer API를 사용하면 어디에서나 콘텐츠를 로드하거나 생성하는 로더를 빌드할 수 있습니다.

예를 들어 원격 API에서 컬렉션 항목을 가져오는 로더를 만들 수 있습니다.

const countries = defineCollection({
  loader: async () => {
    const response = await fetch("https://restcountries.com/v3.1/all");
    const data = await response.json();
    // id 속성이 있는 항목 배열 또는 ID를 키로, 항목을 값으로 하는 객체를 반환해야 합니다.
    return data.map((country) => ({
      id: country.cca3,
      ...country,
    }));
  },
  // 선택적으로 스키마 추가
  // schema: z.object...
});

export const collections = { countries };

더 복잡한 로딩 로직을 위해 객체 로더를 정의할 수 있습니다. 이를 통해 증분 업데이트와 조건부 로딩이 가능해지며, 데이터 저장소에 대한 전체 액세스 권한도 부여할 수 있습니다. Content Layer API RFC에서 API를 참조하세요.

Content Layer API를 사용하기 위해 기존 콘텐츠 컬렉션 마이그레이션하기

기존 콘텐츠 컬렉션을 Markdown, MDX, Markdoc, 또는 JSON 항목으로 변환하여 Content Layer API를 사용할 수 있습니다.

컬렉션 폴더를 src/content/ 외부로 이동합니다 (예: src/data/로). src/content/ 폴더에 있는 모든 컬렉션은 기존 콘텐츠 컬렉션 API를 사용합니다.

기존 src/content/config.ts 파일을 이동하지 마세요. 이 파일은 두 API를 사용하여 모든 컬렉션을 정의합니다.

컬렉션 정의를 수정합니다. 업데이트된 컬렉션에는 loader가 필요하며, 컬렉션 type을 선택하는 옵션은 더 이상 사용할 수 없습니다.

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  // 콘텐츠 레이어의 경우 더 이상 `type`을 정의하지 않습니다.
  type: 'content',
  loader: glob({ pattern: '**\/[^_]*.md', base: "./src/data/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
  }),
});

참조를 slug에서 id로 변경합니다. 콘텐츠 레이어 컬렉션에는 slug 필드가 없습니다. 대신 업데이트된 모든 컬렉션에는 id가 있습니다.

---
export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map((post) => ({
    params: { slug: post.slug },
    params: { slug: post.id },
    props: post,
  }));
}
---

새 render() 함수로 전환합니다. 이제 항목은 직렬화 가능한 일반 객체이므로 더 이상 render() 메서드를 가지지 않습니다. 대신 astro:content에서 render() 함수를 가져옵니다.

---
import { getEntry } from 'astro:content';
import { getEntry, render } from 'astro:content';

const post = await getEntry('blog', params.slug);

const { Content, headings } = await post.render();
const { Content, headings } = await render(post);
---

<Content />

더 알아보기

전체 개요와 전체 API 참조는 Content Layer API RFC를 확인하고 피드백을 공유하세요.

기여하기

커뮤니티

구성 참조

최상위 옵션

site

base

trailingSlash

redirects

output

adapter

integrations

root

예

srcDir

publicDir

outDir

cacheDir

compressHTML

scopedStyleStrategy

security

security.checkOrigin

vite

예

빌드 옵션

build.format

Astro.url에 미치는 영향

build.client

build.server

build.assets

build.assetsPrefix

build.serverEntry

build.redirects

build.inlineStylesheets

서버 옵션

server.host

server.port

server.open

server.headers

개발 툴바 옵션

devToolbar.enabled

프리페치 옵션

prefetch.prefetchAll

prefetch.defaultStrategy

이미지 옵션

image.endpoint

image.service

image.service.config.limitInputPixels

image.domains

image.remotePatterns

Markdown 옵션

markdown.shikiConfig

markdown.syntaxHighlight

markdown.remarkPlugins

markdown.rehypePlugins

markdown.gfm

markdown.smartypants

markdown.remarkRehype

i18n

i18n.defaultLocale

i18n.locales

i18n.fallback

예

i18n.routing

i18n.routing.prefixDefaultLocale

i18n.routing.redirectToDefaultLocale

i18n.routing.manual

Legacy 플래그

Experimental 플래그

experimental.directRenderScript

experimental.actions

experimental.contentCollectionCache

experimental.clientPrerender

experimental.globalRoutePriority

experimental.env

experimental.env.schema

experimental.env.validateSecrets

experimental.serverIslands

서버 아일랜드 대체 콘텐츠

experimental.contentIntellisense

experimental.contentLayer

loader를 사용하여 데이터 가져오기

Content Layer API로 쿼리 및 렌더링하기

`loader`를 사용하여 데이터 가져오기