Astro를 Zephyr에 맞게 구성하기
설정
편집 전에 사이트의 기존 astro.config.*, output 모드 및 어댑터, 설치된 astro 버전을 읽으십시오. 기존 통합 및 옵션은 유지하십시오. zephyr-astro-integration이 없는 경우, 종속성 변경이 승인된 경우에만 설치하십시오. 빌드 시간에만 필요하므로 개발 종속성으로 충분합니다.
설치된 패키지는 astro 피어를 ^4.0.0 || ^5.15.8 || ^6.4.6 || ^7.0.7로 선언하며 Astro가 제공하는 Vite 버전을 사용합니다. integrations의 마지막 항목으로 withZephyr()를 추가하십시오:
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import sitemap from '@astrojs/sitemap';
import { withZephyr } from 'zephyr-astro-integration';
export default defineConfig({
site: 'https://example.com',
integrations: [mdx(), sitemap(), withZephyr()],
});
Astro는 astro:build:done 훅을 목록 순서대로 한 번에 하나씩 실행하며, Zephyr는 해당 훅에서 업로드합니다. 마지막에 배치하면 사이트맵과 같이 이전 통합에서 작성된 파일이 업로드 전에 존재하게 됩니다. 기본 내보내기는 동일한 withZephyr 함수입니다. vite.plugins에 vite-plugin-zephyr를 추가하지 마십시오. 통합 자체가 게시를 처리합니다.
Module Federation
이 통합은 Module Federation을 구성하지 않으며 zephyr:dependencies를 원격 URL로 확인하지 않습니다. mfConfigs 및 federation 옵션은 변경되지 않고 전달되는 게시 메타데이터이며 TAP 패키지에만 필요합니다. 설정하기 전에 게시 세부 정보를 읽으십시오. 공유되는 zephyr-module-federation 가이드는 프로젝트 간 호스트 및 원격 모델을 다룹니다.
정적 출력만 지원
통합은 Astro가 astro:build:done에 전달하는 디렉터리를 업로드하며 서버 진입점이나 스냅샷 유형을 전송하지 않습니다. 해당 디렉터리는 클라이언트 출력이므로 정적 사이트를 게시합니다. output: 'server' 또는 어댑터를 사용하는 경우 클라이언트 및 사전 렌더링된 파일만 게시됩니다. 주문형 라우트, API 엔드포인트 및 미들웨어는 게시되지 않습니다. 이 통합을 SSR 배포 경로로 제시하지 말고, 사용자의 어댑터를 승인 없이 제거하여 맞추려 하지 마십시오. 대신 제한 사항을 보고하십시오.
통합은 또한 사이트의 .env 파일에서 ZE_PUBLIC_* 값을 로드하고 import.meta.env.ZE_PUBLIC_* 및 process.env.ZE_PUBLIC_* 읽기를 다시 작성하여 환경이 빌드 후에 값을 덮어쓸 수 있도록 합니다. 공유되는 zephyr-core 가이드가 해당 모델을 다룹니다.
오해할 수 있는 수정 사항 방지
- 성공적인
astro build를 게시로 간주하지 마십시오. 빌드 훅의 Zephyr 오류는 기록되며ZE_FAIL_BUILD=true가 설정되지 않은 한 빌드는 계속됩니다. 잘못된target만 즉시 예외를 발생시킵니다. - 일반 사이트에
target: 'tap-app'을 설정하지 마십시오. TAP은ZE_PUBLIC_*재작성을 비활성화하고 쌍을 이루는 연합 메타데이터가 필요합니다. - 소스 맵이 게시된다고 가정하지 마십시오. 일반 사이트의 경우
.map파일은 건너뜁니다. ZE_PUBLIC_*에 자격 증명을 넣지 마십시오. 해당 값은 클라이언트에서 볼 수 있습니다.
완료 확인
사이트의 기존 패키지 실행기로 승인된 빌드를 실행하십시오. 출력 디렉터리에 예상 페이지와 자산이 포함되어 있는지, 그리고 Zephyr가 버전 URL과 함께 성공적인 게시를 보고하는지 확인하십시오. 자격 증명 없이 빌드하면 로컬 출력의 정확성을 확인할 수 있지만 실시간 배포 성공은 확인할 수 없습니다. 해당 차이점을 보고하고, 서버 렌더링 라우트가 게시된 항목 밖에 있음을 명확히 밝히십시오.
실패 시, 실행 가능한 오류를 유지하고 일치하는 구성을 수정하십시오. 사이트의 출력 모드를 조용히 변경하거나, 오류를 억제하거나, 부분 빌드가 배포되었다고 주장하지 마십시오.