미디어 라이브러리

미디어 라이브러리는 재사용 가능한 이미지, 문서, 비디오, 오디오를 저장합니다. 편집자는 파일을 한 번 업로드하고, 콘텐츠 필드와 Portable Text에서 선택하며, 어떤 콘텐츠 항목이 로컬 미디어 아이템을 참조하는지 확인할 수 있습니다.

미디어 라이브러리 열기

관리 사이드바에서 Media를 선택합니다. 메인 라이브러리에는 폴더에 배치되지 않은 폴더와 파일이 포함됩니다. 폴더를 선택하여 파일을 탐색하거나 그리드 보기와 리스트 보기 사이를 전환합니다.

사이트에 외부 미디어 제공자가 있는 경우, 각 제공자가 다른 소스로 나타납니다. 제공자 기능은 다양합니다: 소스가 탐색과 선택은 지원하지만 폴더, 로컬 이미지 편집, 삭제는 지원하지 않을 수 있습니다.

파일 업로드

라이브러리에서 업로드

업로드는 파일이 추가되는 즉시 시작됩니다. 새 로컬 파일은 업로드 전에 다른 폴더가 열려 있었더라도 메인 라이브러리에 들어갑니다.

콘텐츠 편집 중 업로드

이미지, 파일, 갤러리, Portable Text 이미지 필드는 미디어 피커를 사용합니다. 필드를 열고 Upload files를 선택한 다음 파일을 선택하거나 드롭합니다. 완료된 업로드는 현재 선택의 일부가 됩니다. 실패한 업로드는 재시도하거나 제거할 수 있도록 표시된 상태로 유지됩니다.

갤러리의 경우, Selected media를 검토하고 이동 컨트롤을 사용하여 Add images를 선택하기 전에 순서를 설정합니다. 단일 이미지 또는 파일의 경우, 업로드 완료 후 Select 또는 Insert image를 선택합니다.

허용 파일 및 크기 제한

로컬 미디어 라이브러리는 기본적으로 다음 파일 그룹을 허용합니다:

• PNG, JPEG, GIF, WebP, AVIF 이미지;
• MP4, WebM, QuickTime 비디오 등 일반적인 비디오 형식;
• MP3, WAV, Ogg 오디오 등 일반적인 오디오 형식;
• PDF 문서.

SVG는 활성 콘텐츠를 포함할 수 있으므로 기본 업로드 목록에서 제외됩니다. 콘텐츠 모델이 더 좁은 선택이나 다른 형식을 필요로 하는 경우, 이미지 또는 파일 필드가 자체 허용 파일 유형 목록을 정의할 수 있습니다. EmDash는 각 파일을 image/png이나 application/pdf와 같은 미디어 유형 레이블로 식별하고, 콘텐츠가 저장될 때 필드의 목록을 다시 확인합니다. 브라우저의 파일 선택기를 변경해도 해당 서버 검사를 우회할 수 없습니다.

기본 최대값은 파일당 50 MB입니다. 사이트 개발자는 maxUploadSize로 변경할 수 있습니다. 제공자가 추가 형식 또는 크기 제한을 부과할 수 있으며 해당 실패를 업로드 행에서 보고합니다.

파일 찾기 및 정리

검색은 부분 파일명과 일치합니다. 유형 필터는 결과를 이미지, 문서, 비디오, 오디오로 제한합니다. 파일명 검색은 폴더가 열려 있을 때도 전체 로컬 라이브러리를 포함합니다. 검색 없이 폴더를 탐색하면 해당 폴더에 할당된 파일만 표시됩니다.

편집자는 메인 라이브러리에서 Add new folder를 선택할 수 있습니다. 로컬 파일을 카드나 행을 표시된 폴더로 드래그하여 이동하거나, 파일을 열고 Location을 변경한 다음 Save를 선택합니다. 파일을 현재 폴더에서 제거하려면 Main library를 위치로 사용합니다.

작성자는 자신이 업로드한 로컬 파일을 이동할 수 있습니다. 편집자는 모든 로컬 파일을 이동할 수 있습니다. 외부 제공자 아이템은 미디어 라이브러리 폴더에 할당할 수 없습니다.

폴더를 삭제하면 파일이 메인 라이브러리로 돌아갑니다. 파일 삭제, URL 변경, 콘텐츠 참조 제거는 수행하지 않습니다.

콘텐츠용 미디어 선택

Portable Text 이미지

Portable Text 필드에 커서를 놓고, 블록 메뉴를 열고 Image를 선택합니다. 이미지를 선택하거나 업로드한 다음 Insert image를 선택합니다. 이후 이미지 블록을 선택하여 대체 텍스트, 캡션, 표시 크기, 정렬을 추가합니다.

이미지 및 파일 필드

Select image나 Select file 같은 필드 작업을 선택한 다음 아이템을 선택하고 선택을 확인합니다. 필드의 MIME 유형 규칙은 표시되는 라이브러리 아이템과 미디어 소스를 제한합니다.

블로그 템플릿의 featured_image 필드는 선택한 미디어 값을 게시물과 함께 저장합니다. 항목을 저장하면 해당 참조가 초안에 저장됩니다. 게시하면 공개 콘텐츠 쿼리에서 사용할 수 있게 됩니다.

갤러리 필드

하나 이상의 이미지를 선택하고, Selected media 아래에서 정렬하고 확인합니다. 갤러리는 여러 위치가 미디어 라이브러리 아이템을 참조하더라도 자체 순서와 이미지별 대체 텍스트 및 캡션을 유지합니다.

콘텐츠에서 사용 중인 이미지 편집

선택한 로컬 이미지는 서로 다른 범위의 작업을 제공합니다:

• Replace는 이 필드, 블록 또는 갤러리 위치에 다른 미디어 라이브러리 아이템을 선택합니다. 원본 아이템을 사용하는 다른 항목은 변경되지 않습니다.
• Edit asset은 기본 미디어 라이브러리 아이템을 엽니다. 메타데이터 변경 및 파괴적 이미지 변경은 해당 아이템의 다른 사용에 영향을 줄 수 있습니다.
• Remove는 이 콘텐츠 참조를 지웁니다. 미디어 라이브러리 아이템은 계속 사용 가능합니다.

Edit asset이 자른 복사본을 만들면, 피커는 현재 사용을 위해 새 복사본을 선택합니다. Portable Text와 갤러리 이미지는 해당 사용의 대체 텍스트, 캡션, 레이아웃, 위치를 유지합니다. Edit asset이 원본을 대체하면, 미디어 ID가 그대로 유지되므로 해당 아이템의 모든 사용이 변경된 이미지를 받습니다.

외부 제공자 이미지와 파일 필드는 Replace와 Remove를 제공하지만 로컬 자산 편집기를 열지 않습니다.

로컬 이미지 대체

Replace image는 기존 미디어 라이브러리 아이템 뒤에 새 바이트를 업로드합니다. 아이템을 참조하는 모든 곳에서 이미지의 새 버전을 표시해야 할 때 사용합니다.

이 작업은 준비된 JPEG, PNG, WebP 아이템에서 사용할 수 있습니다. 작성자는 자신이 업로드한 이미지를 대체할 수 있습니다. 편집자는 모든 로컬 이미지를 대체할 수 있습니다.

EmDash는 미디어 ID, 파일명, URL, 대체 텍스트, 캡션, 폴더를 유지합니다. 따라서 기존 콘텐츠 참조는 계속 작동하며 대체물을 표시합니다. 대체는 저장된 초점을 지웁니다. 좌표가 새 이미지를 설명하지 않을 수 있기 때문입니다.

하나의 필드 또는 이미지 블록만 변경해야 할 때는 콘텐츠 편집기에서 Replace를 대신 사용합니다.

초점 설정

초점은 레이아웃이 이미지를 정사각형, 가로, 세로, 또는 기타 고정 형태로 자를 때 보이도록 유지해야 할 이미지 부분을 표시합니다.

사용자 지정 포인트를 제거하려면 Reset을 선택합니다. 필드나 갤러리용 이미지를 선택하면 EmDash는 자산의 현재 초점을 해당 콘텐츠 값으로 복사합니다. 이미지를 이미 사용하는 콘텐츠는 이미지를 다시 선택할 때까지 저장된 포인트를 유지합니다. 콘텐츠 필드에서 Edit asset을 열면 저장한 포인트로 현재 사용을 업데이트합니다.

로컬 이미지 자르기

자르기는 EmDash가 저장한 준비된 JPEG, PNG, WebP 이미지에서 사용할 수 있습니다. 외부 제공자 이미지는 로컬 자산 편집기에서 자를 수 없습니다.

Replace original은 Original 종횡비에서만 사용할 수 있습니다. Freeform 및 기타 비율에는 Create cropped copy를 사용합니다. 자른 복사본은 원본과 같은 폴더에 유지되며 고유한 파일명을 받습니다.

애니메이션 WebP를 자르면 정지 WebP가 생성됩니다. 자른 결과는 애니메이션을 유지하지 않습니다.

파일 사용 위치 확인

로컬 파일을 열고 Used in을 선택하면 해당 파일을 참조하는 콘텐츠 항목이 나열됩니다. 각 결과는 참조를 포함하는 컬렉션과 필드를 표시하며 편집을 위해 항목을 열 수 있습니다. 휴지통에 있는 항목은 목록에서 식별됩니다.

이 목록이 완전하려면 미디어 사용 추적이 활성화되어 있어야 합니다. 관리자가 사이트에 대해 한 번 활성화합니다:

활성화하면 미디어 사용 추적을 끌 수 없습니다. 캡처가 활성화된 후 새 콘텐츠 변경이 추적됩니다. 백그라운드 스캔은 이미 존재하던 항목의 참조를 추가합니다.

Used in 보기에서 인덱싱이 실행 중이거나, 오래되었거나, 부분적이거나, 실패했다고 보고하면 결과를 불완전한 것으로 취급합니다. 관리자는 Media usage tracking으로 돌아가 현재 상태와 복구 안내를 확인할 수 있습니다.

템플릿에서 이미지 렌더링

이미지 필드는 일반 URL이 아닌 미디어 값을 반환합니다. emdash/ui의 Image로 해당 값을 렌더링하여 로컬 및 제공자 지원 이미지가 적절한 URL, 크기, 초점, 반응형 변형, 저품질 플레이스홀더를 사용하도록 합니다:

---
import { getEmDashEntry } from "emdash";
import { Image } from "emdash/ui";

const { entry: post, error } = await getEmDashEntry("posts", Astro.params.slug);
if (error) return new Response("Unable to load post", { status: 500 });
if (!post) return Astro.redirect("/404");
---

{post.data.featured_image && (
  <Image image={post.data.featured_image} width={1200} height={675} priority />
)}

priority는 페이지 상단에 표시되는 메인 이미지에만 사용합니다. 즉시 로딩을 요청하고 브라우저에 높은 fetch-priority 힌트를 제공합니다. 다른 이미지는 컴포넌트의 기본 지연 로딩을 유지해야 합니다.

필드에 다크 모드 대응이 있는 경우, Image는 두 소스를 모두 렌더링하고 방문자의 색상 구성표에서 하나를 선택합니다. 필드와 템플릿 설정은 다크 모드 이미지를 참조하세요.

템플릿은 추가 미디어 라이브러리 쿼리 없이 콘텐츠 참조와 함께 저장된 미디어 메타데이터를 받습니다. 사용자 지정 통합이 제공자의 최신 메타데이터를 필요로 하는 경우, 해당 아이템을 명시적으로 요청하고 컬렉션 페이지에서 이미지당 제공자 조회를 피합니다. 필드 유형 참조에서 저장된 파일 및 이미지 값을 설명합니다.

스토리지 및 제공자 구성

로컬 라이브러리는 사이트의 구성된 스토리지 어댑터를 통해 파일을 저장합니다. Node.js 사이트는 로컬 디스크 또는 S3 호환 스토리지를 사용할 수 있습니다. Cloudflare 사이트는 일반적으로 R2 바인딩을 사용합니다. 어댑터는 바이트가 저장되는 위치를 결정하며, 미디어 라이브러리는 동일한 작성 워크플로를 유지합니다. 구성 및 프로덕션 영속성 요구 사항은 미디어 스토리지를 참조하세요.

Cloudflare Images와 Cloudflare Stream은 외부 미디어 제공자로 등록할 수 있습니다. 피커에서 소스로 나타나며, Image는 제공자 지원 이미지 값을 이해합니다. 제공자 아이템은 해당 서비스에 의해 관리되므로 로컬 폴더, 초점, 자르기, 대체는 EmDash 자산 편집기에서 해당 아이템에 사용할 수 없습니다.

미디어를 안전하게 삭제

미디어 라이브러리에서 파일을 열고 Delete를 선택하여 영구 삭제를 확인합니다. 작성자는 자신이 업로드한 로컬 파일을 삭제할 수 있습니다. 편집자는 모든 로컬 파일을 삭제할 수 있습니다. 제공자 아이템은 해당 소스가 삭제를 노출하고 현재 사용자에게 권한이 있는 경우에만 제공자에서 삭제됩니다.

자동화된 업로드 및 미디어 관리는 미디어 엔드포인트 참조 또는 CLI 미디어 명령을 참조하세요. 선택한 미디어를 사용하는 항목을 게시하려면 콘텐츠 작업을 계속합니다.