Astro v4로 업그레이드

이 안내서는 Astro v3에서 Astro v4로 마이그레이션하는 데 도움이 됩니다.

이전 프로젝트를 v3으로 업그레이드해야 합니까? 이전 마이그레이션 안내서를 참조하세요.

v3 문서를 확인해야 합니까? 이전 버전의 문서 사이트(관리되지 않는 v3.6 스냅샷)를 방문하세요.

Astro 업그레이드

패키지 관리자를 사용하여 프로젝트의 Astro 버전과 모든 공식 통합을 최신 버전으로 업데이트하세요.

# Astro와 공식 통합을 함께 업그레이드합니다.
npx @astrojs/upgrade

# Astro와 공식 통합을 함께 업그레이드합니다.
pnpm dlx @astrojs/upgrade

# Astro와 공식 통합을 함께 업그레이드합니다.
yarn dlx @astrojs/upgrade

필요한 경우 Astro 통합을 수동으로 업그레이드할 수도 있으며 프로젝트의 다른 종속성을 업그레이드해야 할 수도 있습니다.

Astro v4.0에서는 잠재적 주요 변경 사항이 포함되고, 더 이상 사용되지 않는 일부 기능이 제거되었습니다.

v4.0으로 업그레이드한 후 프로젝트가 예상대로 작동하지 않으면 이 안내서에서 모든 주요 변경 사항에 대한 개요와 코드베이스를 업데이트 방법에 대한 지침을 확인하세요.

전체 릴리스 정보는 변경 로그를 참조하세요.

Astro v4.0 실험적 플래그가 제거됨

devOverlay 실험적 플래그를 제거하고 모든 i18n 구성을 astro.config.mjs 파일의 최상위 수준으로 이동합니다.

import { defineConfig } from 'astro/config';

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

i18n 및 이름이 변경된 devToolbar 구성은 이제 Astro v4.0에서 사용할 수 있습니다.

v4.0 블로그 게시물에서 이 두 가지 흥미로운 기능과 자세한 내용을 읽어보세요!

업그레이드

Astro의 종속성에 대한 주요 업그레이드로 인해 프로젝트가 크게 변경될 수 있습니다.

업그레이드: Vite 5.0

Astro v3.0에서는 Vite 4가 개발 서버 및 프로덕션 번들러로 사용되었습니다.

Astro v4.0에서는 Vite 4에서 Vite 5로 업그레이드되었습니다.

무엇을 해야 하나요?

Vite 특정 플러그인, 구성 또는 API를 사용하는 경우 Vite 마이그레이션 안내서에서 주요 변경 사항을 확인하고 필요에 따라 프로젝트를 업그레이드하세요. Astro 자체에는 큰 변화가 없습니다.

업그레이드: unified, remark, rehype 종속성

Astro v3.x에서는 unified v10 및 호환되는 remark/rehype 패키지를 사용하여 Markdown 및 MDX를 처리했습니다.

Astro v4.0은 unified를 v11로 업그레이드하며, remark/rehype 패키지를 최신 버전으로 업그레이드합니다.

무엇을 해야 하나요?

사용자 정의 remark/rehype 패키지를 사용하는 경우, 패키지 관리자를 사용하여 모든 패키지를 최신 버전으로 업데이트하여 unified v11을 지원하는지 확인하세요. 사용 중인 패키지는 astro.config.mjs에서 찾을 수 있습니다.

적극적으로 업데이트된 패키지를 사용하는 경우, 주요 변경 사항이 없어야 하지만 일부 패키지는 아직 unified v11과 호환되지 않을 수 있습니다. 배포하기 전에 Markdown/MDX 페이지를 시각적으로 검사하여 사이트가 의도한 대로 작동하는지 확인하세요.

주요 변경 사항

다음 변경 사항은 Astro의 주요 변경 사항으로 간주됩니다. 주요 변경 사항은 일시적으로 이전 버전과의 호환성을 제공할 수도 있고 제공하지 않을 수도 있으며, 모든 문서는 현재 지원되는 코드만 참조하도록 업데이트됩니다.

v3.x 프로젝트에 대한 문서를 참조해야 하는 경우, v4.0이 릴리스되기 전 문서의 (유지관리되지 않는) 스냅샷을 찾아볼 수 있습니다.

이름이 변경됨: `entrypoint` (통합 API)

Astro v3.x에서는 경로 진입점을 지정하는 injectRoute 통합 API의 속성 이름이 entryPoint였습니다.

Astro v4.0에서는 다른 Astro API와 일관성을 유지하기 위해 이 속성의 이름을 entrypoint로 변경했습니다. entryPoint 속성은 더 이상 사용되지 않지만 계속 작동하며 코드를 업데이트하라는 경고를 기록합니다.

무엇을 해야 하나요?

injectRoute API를 사용하는 통합이 있는 경우 entryPoint 속성의 이름을 entrypoint로 바꿉니다. Astro 3과 4 버전을 모두 지원하는 라이브러리 작성자인 경우, entryPoint와 entrypoint를 모두 지정할 수 있습니다. 이 경우 경고가 기록되지 않습니다.

injectRoute({
  pattern: '/fancy-dashboard',
  entryPoint: '@fancy/dashboard/dashboard.astro'
  entrypoint: '@fancy/dashboard/dashboard.astro'
});

변경됨: 통합 API의 `app.render` 시그니처

Astro v3.0에서 app.render() 메서드는 routeData와 locals를 별도의 선택적 인수로 허용했습니다.

Astro v4.0은 app.render() 시그니처를 변경합니다. 이제 이 두 가지 속성을 단일 객체에서 사용할 수 있습니다. 객체와 이 두 속성은 모두 선택 사항입니다.

무엇을 해야 하나요?

어댑터를 유지 관리하는 경우, 현재 시그니처는 다음 주요 버전까지 계속 작동합니다. 새 시그니처로 마이그레이션하려면 객체의 속성으로 여러 개의 독립 인수가 아닌 routeData 및 locals를 전달하세요.

app.render(request, routeData, locals)
app.render(request, { routeData, locals })

변경됨: 이제 어댑터는 지원되는 기능을 지정해야 합니다.

Astro v3.x에서는 어댑터가 지원하는 기능을 지정할 필요가 없었습니다.

Astro v4.0에서는 어댑터가 지원하는 기능 목록을 지정하기 위해 supportedAstroFeatures{} 속성을 전달해야 합니다. 이 속성은 더 이상 선택 사항이 아닙니다.

무엇을 해야 하나요?

어댑터 작성자는 지원하는 기능 목록을 지정하기 위해 supportedAstroFeatures{} 옵션을 전달해야 합니다.

export default function createIntegration() {
  return {
    name: '@matthewp/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@matthewp/my-adapter',
          serverEntrypoint: '@matthewp/my-adapter/server.js',
          supportedAstroFeatures: {
              staticOutput: 'stable'
          }
        });
      },
    },
  };
}

제거됨: Shiki 언어 `path` 속성

Astro v3.x에서는 markdown.shikiConfig.langs에 전달된 Shiki 언어가 자동으로 Shikiji 호환 언어로 변환되었습니다. Shikiji는 Astro에서 구문 강조를 위해 사용하는 내부 도구입니다.

Astro v4.0에서는 구성이 혼란스러웠던 Shiki 언어의 path 속성이 제거되었습니다. 이는 langs에 직접 전달할 수 있는 가져오기로 대체됩니다.

무엇을 해야 하나요?

대신 언어 JSON 파일을 가져와서 옵션에 전달해야 합니다.

 import customLang from './custom.tmLanguage.json'

export default defineConfig({
  markdown: {
    shikiConfig: {
      langs: [
       { path: '../../custom.tmLanguage.json' },
       customLang,
      ],
    },
  },
})

더 이상 사용되지 않음

다음과 같이 더 이상 사용되지 않는 기능은 이제 지원되지 않으며, 문서화되지 않습니다. 이에 따라 프로젝트를 업데이트하세요.

일부 사용되지 않는 기능은 완전히 제거될 때까지 일시적으로 계속 작동할 수 있습니다. 또 다른 일부는 더이상 작동하지 않거나, 코드를 업데이트하라는 오류를 발생시킬 수 있습니다.

더 이상 사용되지 않음: View Transitions의 `submit` 이벤트를 위한 `handleForms`

Astro v3.x에서는 <ViewTransitions /> 컴포넌트를 사용하는 프로젝트에서 form 요소에 대한 submit 이벤트 처리를 선택해야 했습니다. 이는 handleForms 속성을 전달하여 수행되었습니다.

Astro v4.0에서는 <ViewTransitions />가 사용될 때 기본적으로 form 요소에 대한 submit 이벤트를 처리합니다. handleForms 속성은 더 이상 사용되지 않으며 아무런 효과가 없습니다.

무엇을 해야 하나요?

ViewTransitions 컴포넌트에서 handleForms 속성을 제거합니다. 더 이상 필요하지 않습니다.

---
import { ViewTransitions } from "astro:transitions";
---
<html>
  <head>
    <ViewTransitions handleForms />
  </head>
  <body>
    <!-- 다른 코드 -->
  </body>
</html>

submit 이벤트 처리를 선택 해제하려면, 관련 form 요소에 data-astro-reload 속성을 추가하세요.

<form action="/contact" data-astro-reload>
  <!-- -->
</form>

더 이상 사용되지 않는 기능 제거

다음과 같이 더 이상 사용되지 않는 기능은 이제 코드 베이스에서 완전히 제거되어 더 이상 사용할 수 없습니다. 이러한 기능 중 일부는 지원 중단 후에도 프로젝트에서 계속 작동할 수 있습니다. 또 다른 일부는 아무런 효과가 없었을 수도 있습니다.

이제 이러한 제거된 기능을 포함하는 프로젝트는 빌드할 수 없으며, 더 이상 이러한 기능을 제거하라는 메시지를 표시하는 문서도 지원되지 않습니다.

제거됨: 엔드포인트에서 단순 객체 반환

Astro v3.x에서는 엔드포인트에서 단순 객체를 반환하는 것이 더 이상 사용되지 않지만, Astro v2와의 호환성을 유지하기 위해 계속 지원되었습니다. 마이그레이션을 쉽게 하기 위해 ResponseWithEncoding 유틸리티도 제공되었습니다.

Astro v4.0은 단순 객체에 대한 지원을 제거하고 엔드포인트가 항상 Response를 반환하도록 요구합니다. 적절한 Response 타입을 위해 ResponseWithEncoding 유틸리티도 제거되었습니다.

무엇을 해야 하나요?

Response 객체를 직접 반환하도록 엔드포인트를 업데이트하세요.

export async function GET() {
  return { body: { "title": "Bob의 블로그" }};
  return new Response(JSON.stringify({ "title": "Bob의 블로그" }));
}

ResponseWithEncoding 사용을 제거하려면, 대신 ArrayBuffer를 사용하도록 코드를 리팩토링하세요.

export async function GET() {
  const file = await fs.readFile('./bob.png');
  return new ResponseWithEncoding(file.toString('binary'), undefined, 'binary');
  return new Response(file.buffer);
}

제거됨: `build.split` 및 `build.excludeMiddleware`

Astro v3.0에서는 build.split 및 build.excludeMiddleware 빌드 구성 옵션이 더 이상 사용되지 않으며, 동일한 작업을 수행하기 위한 어댑터 구성 옵션으로 대체되었습니다.

Astro v4.0은 이러한 속성을 완전히 제거합니다.

무엇을 해야 하나요?

더 이상 사용되지 않는 build.split 또는 build.excludeMiddleware를 사용하는 경우, 더 이상 존재하지 않으므로 이제 제거해야 합니다.

더 이상 사용되지 않는 미들웨어 속성을 어댑터 구성으로 업데이트하려면 v3 마이그레이션 안내서를 참조하세요.

제거됨: `Astro.request.params`

Astro v3.0에서는 Astro.request.params API가 더 이상 사용되지 않지만 이전 버전과의 호환성을 위해 보존되었습니다.

Astro v4.0에서는 이 옵션이 완전히 제거되었습니다.

무엇을 해야 하나요?

지원되는 대체 항목인 Astro.params로 모두 업데이트합니다.

const { id } = Astro.request.params;
const { id } = Astro.params;

제거됨: `markdown.drafts`

Astro v3.0에서는 markdown.drafts를 사용하여 초안 게시물 작성을 제어하는 것이 더 이상 사용되지 않습니다.

Astro v4.0에서는 이 옵션이 완전히 제거되었습니다.

무엇을 해야 하나요?

더 이상 사용되지 않는 markdown.drafts를 사용하는 경우, 더 이상 존재하지 않으므로 이제 제거해야 합니다.

프로젝트의 일부 페이지를 계속해서 초안으로 표시하려면, 콘텐츠 컬렉션으로 마이그레이션하고, 대신 draft: true 프런트매터 속성을 사용하여 페이지를 수동으로 필터링하세요.

제거됨: `getHeaders()`

Astro v3.0에서는 getHeaders() Markdown 내보내기가 더 이상 사용되지 않으며 getHeadings()로 대체되었습니다.

Astro v4.0에서는 이 옵션이 완전히 제거되었습니다.

무엇을 해야 하나요?

더 이상 사용되지 않는 getHeaders()를 사용하는 경우, 더 이상 존재하지 않으므로 이제 제거해야 합니다. 모든 인스턴스를 지원되는 대체 기능인 getHeadings()로 바꿉니다.

const posts = await Astro.glob('../content/blog/*.mdx');
const firstPostHeadings = posts.at(0).getHeaders();
const firstPostHeadings = posts.at(0).getHeadings();

제거됨: `getStaticPaths()`에서 `rss` 사용

Astro v3.0에서는 getStaticPaths()에서 더 이상 사용되지 않는 rss 도우미를 사용하면 오류가 발생합니다.

Astro v4.0은 이 도우미를 완전히 제거합니다.

무엇을 해야 하나요?

RSS 피드를 생성하기 위해 더 이상 지원되지 않는 방법을 사용하고 있다면, 이제 완전한 RSS 설정을 위해 @astrojs/rss 통합을 사용해야 합니다.

제거됨: 소문자 HTTP 메서드 이름

Astro v3.0에서는 소문자 HTTP 요청 메서드 이름 (get, post, put, all, del)이 더 이상 사용되지 않습니다.

Astro v4.0은 소문자 이름에 대한 지원을 완전히 제거합니다. 이제 모든 HTTP 요청 메소드는 대문자를 사용하여 작성해야 합니다.

무엇을 해야 하나요?

더 이상 사용되지 않는 소문자 이름을 사용하는 경우 이제 해당 이름을 해당하는 대문자로 바꿔야 합니다.

대문자 HTTP 요청 방법을 사용하는 지침은 v3 마이그레이션 가이드를 참조하세요.

제거됨: `base` 접두사가 누락된 경우 301 리디렉션

Astro v3.x에서 Astro 프리뷰 서버는 기본 경로 없이 public 디렉터리 자산에 액세스할 때 301 리디렉션을 반환했습니다.

Astro v4.0은 프리뷰 서버가 실행중일 때, public 디렉터리 자산에 대해 기본 경로 접두사 없이 404 상태를 반환하여 개발 서버와 동작을 일치시킵니다.

무엇을 해야 하나요?

Astro 프리뷰 서버를 사용할 때, public 디렉터리의 모든 정적 자산 가져오기 및 URL의 경로 앞에는 base 접두사가 있어야 합니다.

다음 예시는 base: '/docs'가 구성된 경우, public 폴더의 이미지를 표시하는 데 필요한 src 속성을 보여줍니다.

// To access public/images/my-image.png:

<img src="/docs/images/my-image.png" alt="">

제거됨: `astro/client-image` 자동 변환

Astro v3.x에서는 astro/client-image 타입(더 이상 사용되지 않는 이미지 통합에 사용됨)이 제거되었지만, env.d.ts 파일에 있는 경우, 기본 Astro 타입인 astro/client로 자동 변환되었습니다.

Astro v4.0은 astro/client-image를 무시하고 더 이상 env.d.ts를 자동으로 업데이트하지 않습니다.

무엇을 해야 하나요?

src/env.d.ts 파일에 @astrojs/image에 대한 타입이 구성되어 있고 v3.0으로 업그레이드해도 타입이 자동으로 변환되지 않는 경우, 수동으로 astro/client-image 타입을 astro/client로 바꾸세요.

  /// <reference types="astro/client-image" />
  /// <reference types="astro/client" />

커뮤니티 자료

Astro v4.0에 대한 좋은 리소스를 알고 계십니까? 이 페이지를 편집하고 아래에 링크를 추가하세요!

알려진 문제

보고된 문제가 있는지 GitHub에서 Astro의 issues를 확인하거나 직접 문제를 보고해주세요.

Astro v4로 업그레이드

Astro 업그레이드

Astro v4.0 실험적 플래그가 제거됨

업그레이드

업그레이드: Vite 5.0

무엇을 해야 하나요?

업그레이드: unified, remark, rehype 종속성

무엇을 해야 하나요?

주요 변경 사항

이름이 변경됨: entrypoint (통합 API)

무엇을 해야 하나요?

변경됨: 통합 API의 app.render 시그니처

무엇을 해야 하나요?

변경됨: 이제 어댑터는 지원되는 기능을 지정해야 합니다.

무엇을 해야 하나요?

제거됨: Shiki 언어 path 속성

무엇을 해야 하나요?

더 이상 사용되지 않음

더 이상 사용되지 않음: View Transitions의 submit 이벤트를 위한 handleForms

무엇을 해야 하나요?

더 이상 사용되지 않는 기능 제거

제거됨: 엔드포인트에서 단순 객체 반환

무엇을 해야 하나요?

제거됨: build.split 및 build.excludeMiddleware

무엇을 해야 하나요?

제거됨: Astro.request.params

무엇을 해야 하나요?

제거됨: markdown.drafts

무엇을 해야 하나요?

제거됨: getHeaders()

무엇을 해야 하나요?

제거됨: getStaticPaths()에서 rss 사용

무엇을 해야 하나요?

제거됨: 소문자 HTTP 메서드 이름

무엇을 해야 하나요?

제거됨: base 접두사가 누락된 경우 301 리디렉션

무엇을 해야 하나요?

제거됨: astro/client-image 자동 변환

무엇을 해야 하나요?

커뮤니티 자료

알려진 문제

이름이 변경됨: `entrypoint` (통합 API)

변경됨: 통합 API의 `app.render` 시그니처

제거됨: Shiki 언어 `path` 속성

더 이상 사용되지 않음: View Transitions의 `submit` 이벤트를 위한 `handleForms`

제거됨: `build.split` 및 `build.excludeMiddleware`

제거됨: `Astro.request.params`

제거됨: `markdown.drafts`

제거됨: `getHeaders()`

제거됨: `getStaticPaths()`에서 `rss` 사용

제거됨: `base` 접두사가 누락된 경우 301 리디렉션

제거됨: `astro/client-image` 자동 변환