Cloudinary & Astro

Cloudinary는 이미지 및 동영상 플랫폼이자 헤드리스 디지털 자산 관리자 (DAM)로, 콘텐츠 전송 네트워크 (CDN)에 자산을 호스팅하고 전송할 수 있는 서비스입니다.

Cloudinary에서 제공하는 경우, 배경 제거, 동적 자르기 및 크기 조정, 생성형 AI와 같은 도구를 사용하여 자산을 편집할 수 있는 Transformation API에 추가로 액세스할 수 있습니다.

Astro에서 Cloudinary 사용

Cloudinary는 Astro 환경에 따라 사용할 수 있는 다양한 SDK를 지원합니다.

Cloudinary Astro SDK는 이미지, 동영상, 업로드 컴포넌트를 포함한 기본 Astro 컴포넌트와 Astro 콘텐츠 컬렉션과 함께 사용할 수 있는 콘텐츠 로더를 제공합니다.

또는 Cloudinary Node.js SDK와 JavaScript SDK를 모두 사용하여 이미지의 URL을 생성할 수 있습니다. Node.js SDK는 Cloudinary API에 자산 업로드, 리소스 요청, 콘텐츠 분석 실행 등 추가 요청을 할 수 있습니다.

전제 조건

기존 Astro 프로젝트
Cloudinary 계정

Astro Cloudinary 설치

패키지 관리자에 적합한 명령을 실행하여 Cloudinary Astro SDK를 설치합니다:

npm install astro-cloudinary

pnpm add astro-cloudinary

yarn add astro-cloudinary

계정 구성

프로젝트의 루트에 새 .env 파일을 만들고 Cloudinary 자격 증명을 추가합니다:

PUBLIC_CLOUDINARY_CLOUD_NAME="<클라우드 이름>"

// CldUploadWidget 또는 cldAssetsLoader를 사용하는 경우에만 필요합니다.
PUBLIC_CLOUDINARY_API_KEY="<API 키>"
CLOUDINARY_API_SECRET="<API 비밀>"

Cloudinary 이미지 사용

이미지 데이터 (예: src, width, alt)를 <CldImage> 컴포넌트에 전달하여 .astro 컴포넌트에 이미지를 추가합니다. 이렇게 하면 이미지가 자동으로 최적화되고 Transformations API에 액세스할 수 있습니다.

---
import { CldImage } from 'astro-cloudinary';
---
<CldImage
  src="<Public ID>"
  width="<Width>"
  height="<Height>"
  alt="<Description>"
/>

자세한 내용은 Cloudinary의 <CldImage> 문서를 참조하세요.

Cloudinary 동영상 사용

.astro 컴포넌트에 동영상을 추가하려면 <CldVideoPlayer>를 추가하고 적절한 속성을 전달하세요. 이 컴포넌트는 Cloudinary 비디오 플레이어를 사용하여 동영상을 자동으로 최적화하고 임베드합니다.

---
import { CldVideoPlayer } from 'astro-cloudinary';
---
<CldVideoPlayer
  src="<Public ID>"
  width="<Width>"
  height="<Height>"
/>

자세한 내용은 Cloudinary의 <CldVideoPlayer> 문서를 참조하세요.

Cloudinary 업로드 활성화

웹사이트나 앱의 UI에서 파일 업로드를 활성화하려면 Cloudinary Upload Widget을 임베드하는 <CldUploadWidget>을 추가합니다.

다음 예시는 서명되지 않은 Upload Preset을 전달하여 서명되지 않은 업로드를 허용하는 위젯을 만듭니다:

---
import { CldUploadWidget } from 'astro-cloudinary';
---
<CldUploadWidget uploadPreset="<Upload Preset>">
  <button>Upload</button>
</CldUploadWidget>

서명된 업로드에 대한 가이드 및 예시는 Astro Cloudinary 문서에서 확인할 수 있습니다.

자세한 내용은 Cloudinary의 <CldUploadWidget> 문서를 참조하세요.

Cloudinary 콘텐츠 로더

Cloudinary Astro SDK는 콘텐츠 컬렉션을 위한 Cloudinary 자산을 불러오는 cldAssetsLoader 콘텐츠 로더를 제공합니다.

이미지 또는 동영상 컬렉션을 불러오려면 loader: cldAssetsLoader ({})의 folder를 설정합니다 (필요한 경우):

import { defineCollection } from 'astro:content';
import { cldAssetsLoader } from 'astro-cloudinary/loaders';

export const collections = {
  assets: defineCollection({
    loader: cldAssetsLoader({
      folder: '<Folder>' // 선택 사항, 루트 디렉터리를 불러오지 않음
    })
  }),
}

그런 다음 getCollection() 또는 getEntry() 쿼리 함수를 사용하여 컬렉션에서 하나 이상의 이미지 또는 동영상을 선택할 수 있습니다.

자세한 내용은 Cloudinary의 cldAssetsLoader 문서를 참조하세요.

Cloudinary 이미지 URL 생성

Astro Cloudinary SDK는 이미지의 URL을 생성하고 사용하기 위한 getCldOgImageUrl() 헬퍼를 제공합니다. 이미지를 표시하기 위해 컴포넌트 대신 URL이 필요할 때 이 함수를 사용하세요.

URL의 일반적인 용도 중 하나는 소셜 미디어 카드를 위한 <meta> 태그의 오픈 그래프 이미지입니다. 이 헬퍼는 컴포넌트와 마찬가지로 Cloudinary transformations에 액세스하여 모든 페이지에 대한 동적이고 고유한 소셜 카드를 만들 수 있습니다.

다음 예시는 소셜 미디어 카드에 필요한 <meta> 태그와 getCldOgImageUrl()을 사용하여 오픈 그래프 이미지를 생성하는 방법을 보여줍니다:

---
import { getCldOgImageUrl } from 'astro-cloudinary/helpers';
const ogImageUrl = getCldOgImageUrl({ src: '<Public ID>' });
---
<meta property="og:image" content={ogImageUrl} />
<meta property="og:image:secure_url" content={ogImageUrl} />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="twitter:title" content="<Twitter Title>" />
<meta property="twitter:card" content="summary_large_image" />
<meta property="twitter:image" content={ogImageUrl} />

Cloudinary 문서에서 Cloudinary 소셜 미디어 카드 템플릿을 찾으세요.

자세한 내용은 Cloudinary의 getCldOgImageUrl() 문서를 참조하세요.

Node.js에서 Cloudinary 사용

Astro Node.js 환경에서 작업할 때, 보다 복잡한 자산 관리, 업로드 또는 분석이 필요한 경우 Cloudinary Node.js SDK를 사용할 수 있습니다.

패키지 관리자에 적합한 명령을 실행하여 Cloudinary Node.js SDK를 설치합니다:

npm install cloudinary

pnpm add cloudinary

yarn add cloudinary

.env 파일에 다음 환경 변수를 추가합니다:

PUBLIC_CLOUDINARY_CLOUD_NAME="<Your Cloud Name>"
PUBLIC_CLOUDINARY_API_KEY="<Your API Key>"
CLOUDINARY_API_SECRET="<Your API Secret>"

Astro 컴포넌트의 펜스 사이에 다음 코드를 추가하여 새 Cloudinary 인스턴스로 계정을 구성합니다:

---
import { v2 as cloudinary } from "cloudinary";

cloudinary.config({
  cloud_name: import.meta.env.PUBLIC_CLOUDINARY_CLOUD_NAME,
  api_key: import.meta.env.PUBLIC_CLOUDINARY_API_KEY,
  api_secret: import.meta.env.CLOUDINARY_API_SECRET,
});
---

이렇게 하면 이미지, 동영상 및 기타 지원되는 파일과 상호 작용할 수 있는 모든 Cloudinary API에 액세스할 수 있습니다.

await cloudinary.uploader.upload('./path/to/file');

Astro Forms와 Cloudinary Node.js SDK를 사용하여 파일을 업로드하는 방법을 알아보세요.

공식 리소스

더 많은 DAM 안내서

Cloudinary

기여하기

커뮤니티