미디어 라이브러리

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

미디어 라이브러리 열기

관리자 사이드바에서 Media를 선택합니다. Main library에는 폴더와 아직 폴더에 넣지 않은 파일이 들어 있습니다. 폴더를 선택하면 그 안의 파일을 둘러볼 수 있고, 그리드 보기와 목록 보기를 전환할 수도 있습니다.

사이트에 외부 미디어 프로바이더가 있으면 각 프로바이더가 또 다른 소스로 표시됩니다. 프로바이더마다 기능이 다릅니다. 어떤 소스는 탐색과 선택은 지원하지만 폴더, 로컬 이미지 편집, 삭제는 지원하지 않을 수 있습니다.

파일 업로드

라이브러리에서 업로드

파일을 추가하는 즉시 업로드가 시작됩니다. 새 로컬 파일은 업로드 전에 다른 폴더가 열려 있었더라도 Main library에 들어갑니다.

콘텐츠 편집 중 업로드

이미지, 파일, 갤러리, Portable Text 이미지 필드는 미디어 선택기를 사용합니다. 필드를 열고 Upload files를 선택한 다음 파일을 고르거나 놓습니다. 완료된 업로드는 현재 선택에 포함되고, 실패한 업로드는 계속 표시되므로 다시 시도하거나 제거할 수 있습니다.

갤러리의 경우 Selected media를 확인하고 이동 컨트롤로 순서를 정한 다음 Add images를 선택하세요. 단일 이미지나 파일은 업로드가 끝난 후 Select 또는 Insert image를 선택합니다.

허용 파일 및 크기 제한

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

• PNG, JPEG, GIF, WebP, AVIF 이미지
• MP4, WebM, QuickTime 동영상 같은 일반적인 동영상 형식
• MP3, WAV, Ogg 오디오 같은 일반적인 오디오 형식
• PDF 문서

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

기본 최대 크기는 파일당 50 MB입니다. 사이트 개발자는 maxUploadSize로 이를 변경할 수 있습니다. 프로바이더가 형식이나 크기에 추가 제한을 둘 수 있으며, 그 실패는 업로드 행에 표시됩니다.

파일 찾기 및 정리

검색은 파일 이름의 일부와도 일치합니다. 유형 필터를 쓰면 결과를 이미지, 문서, 동영상, 오디오로 제한할 수 있습니다. 파일 이름 검색은 폴더가 열려 있어도 로컬 라이브러리 전체를 대상으로 합니다. 검색하지 않고 폴더를 탐색하면 그 폴더에 할당된 파일만 표시됩니다.

편집자는 Main library에서 Add new folder를 선택할 수 있습니다. 로컬 파일을 옮기려면 카드나 행을 보이는 폴더로 끌어다 놓거나, 파일을 열어 Location을 바꾸고 Save를 선택하세요. 파일을 현재 폴더에서 빼려면 위치로 Main library를 지정합니다.

작성자는 자신이 업로드한 로컬 파일을 옮길 수 있습니다. 편집자는 모든 로컬 파일을 옮길 수 있습니다. 외부 프로바이더의 항목은 미디어 라이브러리 폴더에 할당할 수 없습니다.

폴더를 삭제하면 그 안의 파일은 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을 선택하면 그 파일을 참조하는 콘텐츠 항목과 사이트 설정이 나열됩니다. 각 콘텐츠 결과에는 참조가 들어 있는 컬렉션과 필드의 이름이 표시되며, 항목을 열어 편집할 수 있습니다. 휴지통에 있는 항목은 목록에서 구분되어 표시됩니다. Site Settings 결과에는 그 파일을 선택한 설정(Logo, Favicon, Default Social Image)이 표시됩니다.

Used in은 다음 참조를 확인합니다.

• 이미지 및 파일 필드
• 리피터 안의 이미지 필드
• blocks 필드 안의 이미지, 파일, Portable Text 필드
• Portable Text 필드의 이미지, 갤러리, 동영상 블록
• 사이트 로고, favicon, 기본 소셜 이미지

사용 현황 범위가 완전하고 파일에 이러한 참조가 하나도 없으면 목록에 No tracked references found가 표시됩니다. 범위가 완전해지기 전에는 빈 목록에 No usage to show yet이 표시됩니다.

콘텐츠 결과가 완전해지려면 미디어 사용 추적이 활성화되어 있어야 합니다. 사이트 설정은 추적이 활성화되어 있든 아니든 나열됩니다. 관리자는 사이트에서 추적을 한 번만 켜면 됩니다.

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

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

템플릿에서 이미지 렌더링

이미지 필드는 일반 URL이 아니라 미디어 값을 반환합니다. 로컬 이미지와 프로바이더가 제공하는 이미지가 적절한 URL, 크기, 초점, 반응형 변형, 저화질 플레이스홀더를 사용하도록 emdash/ui의 Image로 그 값을 렌더링하세요.

---
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.rewrite("/404");
---

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

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

필드에 다크 모드용 이미지가 있으면 Image는 두 소스를 모두 렌더링하고 방문자의 색 구성표에 따라 하나를 선택합니다. 필드와 템플릿 설정은 다크 이미지 변형을 참고하세요.

템플릿은 콘텐츠 참조와 함께 저장된 미디어 메타데이터를 미디어 라이브러리에 다시 쿼리하지 않고 받습니다. 사용자 지정 통합에서 프로바이더의 최신 메타데이터가 필요하다면 해당 항목을 명시적으로 요청하고, 컬렉션 페이지에서 이미지마다 프로바이더를 조회하는 일은 피하세요. 저장되는 파일 및 이미지 값은 필드 타입 참조에서 설명합니다.

템플릿에서 파일 렌더링

미디어 라이브러리의 파일 필드 값에는 바로 쓸 수 있는 URL이 없습니다. 해당 값의 meta.storageKey를 Astro.locals.emdash.getPublicMediaUrl()에 전달하세요. 이 함수는 공개 URL을 반환하며, 미디어 테이블을 조회하지 않고도 설정된 R2 또는 S3 공개 도메인을 반영합니다. 스토리지 키가 없는 이전 값은 URL을 url에 유지하고, URL로 추가한 파일(provider: "external"로 저장됨)은 src에 유지합니다.

Cloudflare Stream처럼 등록된 미디어 프로바이더의 파일은 src에 파일 자체가 아니라 미리보기 이미지가 들어 있으므로, 이 방법을 적용할 수 없습니다.

다음 페이지는 video 파일 필드에 저장된 동영상을 렌더링합니다.

---
import { getEmDashEntry } from "emdash";

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

const file = entry.data.video;
const storageKey = typeof file?.meta?.storageKey === "string" ? file.meta.storageKey : undefined;
const url = storageKey
  ? Astro.locals.emdash?.getPublicMediaUrl?.(storageKey)
  : file?.provider === "external"
    ? file.src
    : file?.url;
---

{url && <video src={url} controls preload="metadata" />}

같은 URL은 다운로드 링크나 파일 주소가 필요한 다른 요소에도 사용할 수 있습니다. 값에 들어 있는 파일 이름, MIME 유형, 크기는 파일을 선택할 때 저장된 값입니다.

스토리지 및 프로바이더 구성

로컬 라이브러리는 사이트에 구성된 스토리지 어댑터를 통해 파일을 저장합니다. Node.js 사이트는 로컬 디스크나 S3 호환 스토리지를 사용할 수 있고, Cloudflare 사이트는 보통 R2 바인딩을 사용합니다. 바이트를 어디에 저장할지는 어댑터가 결정하며, 미디어 라이브러리는 같은 작성 워크플로를 유지합니다. 구성 방법과 프로덕션 영속성 요구 사항은 미디어 스토리지 선택을 참고하세요.

Cloudflare Images와 Cloudflare Stream은 외부 미디어 프로바이더로 등록할 수 있습니다. 이들은 선택기에 소스로 표시되며, Image는 프로바이더가 제공하는 이미지 값을 이해합니다. 프로바이더의 항목은 계속 해당 서비스가 관리하므로, EmDash 에셋 편집기에서는 이러한 항목에 대해 로컬 폴더, 초점, 자르기, 교체를 사용할 수 없습니다.

미디어 안전하게 삭제

미디어 라이브러리에서 파일을 열고 Delete를 선택한 다음 영구 삭제를 확인합니다. 작성자는 자신이 업로드한 로컬 파일을 삭제할 수 있고, 편집자는 모든 로컬 파일을 삭제할 수 있습니다. 프로바이더 항목은 해당 소스가 삭제 기능을 제공하고 현재 사용자에게 권한이 있을 때만 프로바이더에서 삭제됩니다.

자동화된 업로드와 미디어 관리에 대해서는 미디어 엔드포인트 참조 또는 CLI 미디어 명령을 참고하세요. 선택한 미디어를 사용하는 항목을 게시하려면 콘텐츠 작업으로 이어서 진행하세요.