WordPress에서 마이그레이션

EmDash 관리자를 사용해 WordPress 사이트를 분석하고, 호환되는 컬렉션을 준비하고, 콘텐츠를 가져오고, 미디어를 복사하고, URL을 다시 작성합니다. 가져온 사이트가 검증을 통과할 때까지는 WordPress 사이트를 계속 사용할 수 있는 상태로 유지하세요.

시작하기 전에

다음 항목을 준비하세요.

• WordPress 데이터베이스와 wp-content/uploads의 백업.
• 미디어를 복사할 계획이라면 스토리지가 구성된 EmDash 사이트.
• EmDash 관리자 계정. WordPress 가져오기에는 import:execute 권한이 필요합니다.
• 완전한 WordPress eXtended RSS(WXR) 내보내기 파일, 또는 WordPress 사이트에 설치한 EmDash Exporter 플러그인 중 하나.

현재의 퍼머링크 구조, 정식 오리진, 리디렉션, 메뉴, 활성 게시물 유형, 택소노미, 그리고 새 사이트가 보존해야 하는 플러그인 소유 필드를 기록해 두세요.

가져오기 방법 선택

exporter 없이 사이트 URL을 입력하면 공개 WordPress REST API만 조사합니다. 이 조사로는 WordPress를 감지하고 공개된 게시물, 페이지, 미디어의 수를 셀 수 있지만, REST를 통한 직접 가져오기는 수행할 수 없습니다.

WXR 파일 내보내기

WordPress에서 Tools → Export를 열고 All content를 선택한 다음 XML 내보내기 파일을 다운로드합니다. WXR 파일은 WordPress 오리진에 있는 미디어를 가리키며, 첨부 파일의 바이트 데이터는 포함하지 않습니다.

EmDash Exporter 연결

WordPress에서 Tools → EmDash Migration을 열고 마이그레이션 키를 생성합니다. 그 키를 EmDash 가져오기 페이지에 붙여 넣습니다.

WordPress 사이트 URL을 입력할 수도 있습니다. exporter가 감지되면 WordPress 애플리케이션 비밀번호 화면을 통해 EmDash를 승인합니다. 로컬 HTTP 개발 사이트에서는 인증 콜백에 HTTPS가 필요하므로 WordPress 사용자 이름과 애플리케이션 비밀번호를 직접 입력합니다.

관리자에서 가져오기

변환 동작

상태

가져오기 도구는 WordPress 상태를 다음과 같이 매핑합니다.

예약된 날짜와 WordPress의 공개 범위 규칙은 이 상태로부터 재구성되지 않습니다. 게시하기 전에 가져온 모든 초안을 검토하세요.

리치 텍스트와 재사용 가능한 블록

Gutenberg 마크업은 Portable Text로 변환됩니다. 클래식 HTML도 같은 변환기로 처리됩니다. 복잡한 블록, 임베드, 숏코드, 페이지 빌더 마크업, 플러그인이 정의한 블록은 렌더링된 EmDash 사이트에서 확인하세요.

WXR의 wp_block 항목은 sections로 가져옵니다. 일반 콘텐츠 컬렉션으로는 가져오지 않습니다.

컬렉션과 필드

기본 게시물 유형 매핑에는 post에서 posts, page에서 pages가 포함됩니다. 커스텀 게시물 유형은 정리된 컬렉션 슬러그를 사용합니다. 준비 단계에서는 분석에 필요한 표준 제목, Portable Text 콘텐츠, 요약, 대표 이미지 필드를 추가합니다.

유형이 호환되는 기존 필드는 재사용됩니다. 유형이 맞지 않으면 해당 컬렉션 매핑이 차단되며, 가져오기 도구는 기존 필드를 다른 유형으로 강제 변환하지 않습니다.

사용자 정의 필드 및 SEO 데이터

WXR 분석은 내부용이 아닌 post-meta 키를 보고하고 필드 이름과 유형을 제안하지만, WXR 데이터베이스 가져오기는 임의의 meta 키를 모두 복사하는 대신 표준 가져오기 필드를 기록합니다. 분석 결과는 별도로 변환해야 할 수 있는 필드의 체크리스트로 활용하세요.

대상 컬렉션에 일치하는 필드가 있으면 EmDash Exporter 경로는 사용자 정의 meta와 Advanced Custom Fields(ACF) 값을 복사할 수 있습니다. 가져오기 스위치가 활성화되어 있다면, 지원되는 대표 이미지 필드와 Yoast 또는 Rank Math SEO 필드를 만들고 값을 채울 수도 있습니다. 직렬화된 PHP 값, 리피터, 유연한 콘텐츠, 플러그인별 구조는 WordPress에서의 표현이 EmDash 필드 유형과 일치한다고 가정하지 말고 직접 검토하세요.

작성자와 Byline

매핑된 WordPress 작성자는 항목 소유자가 됩니다. 표시되는 크레디트에는 Byline을 사용합니다. 사용자 매핑이 없으면 EmDash는 WordPress 작성자 정보를 바탕으로 게스트 Byline을 만들거나 재사용합니다.

택소노미

카테고리와 태그는 일치하는 EmDash 택소노미 정의로 가져옵니다. exporter 경로에서는 커스텀 택소노미의 정의를 만들 수 있습니다. 일치하는 EmDash 정의가 없는 WXR 커스텀 택소노미는 누락으로 보고되며, 그 지정은 건너뜁니다.

미디어

미디어 중복 제거는 다운로드한 바이트 데이터의 SHA-1 해시를 비교합니다. 같은 해시를 가진 기존 미디어 행은 재사용됩니다. 파일 이름과 WordPress ID는 중복 제거의 키가 아닙니다.

EmDash가 첨부 파일을 다운로드하는 동안에는 원본 사이트에 계속 접근할 수 있어야 합니다. 첨부 파일 URL에서 오는 리디렉션은 따라가기 전에 검증됩니다.

부분 가져오기 재시도

관리자 가져오기는 기존 항목을 건너뛰도록 설계되어 있지만, 일치 기준의 경계가 중요합니다.

• 기존 콘텐츠는 WordPress ID가 아니라 컬렉션, 슬러그, 로케일로 일치시킵니다.
• 시도 사이에 원본 슬러그가 바뀌었다면 두 항목을 모두 확인하고 중복을 수동으로 해결하세요.
• 미디어 단계를 다시 실행하면 이미 저장된 바이트가 동일한 파일을 콘텐츠 해시로 재사용합니다.
• exporter 흐름은 크기가 제한된 청크로 전송합니다. 브라우저 흐름을 다시 시작하면 콘텐츠 페이지를 다시 실행하고, 건너뛴 항목으로부터 관계 맵을 다시 구성합니다.

관리자는 WXR 재개 파일을 보존하지 않습니다. emdash import wordpress의 --resume 플래그는 변환된 JSON 파일을 디스크에 기록하는 별도의 CLI 워크플로에 속하며, 관리자 데이터베이스 가져오기를 재개하지 않습니다.

전환 전 검증

가져온 사이트를 원본과 비교하여 확인합니다.

• 게시물 유형과 상태별로 항목 수를 센다.
• 대표적인 Gutenberg, 클래식 에디터, 숏코드, 페이지 빌더 콘텐츠를 연다.
• 대표 이미지와 인라인 미디어가 EmDash URL에서 해석되는지 확인한다.
• 작성자, Byline, 카테고리, 태그, 커스텀 택소노미, 번역을 확인한다.
• exporter로 가져온 경우 메뉴, 댓글, 사이트 식별 정보, SEO 필드를 테스트한다.
• 이전 공개 URL을 크롤링하고 변경된 모든 라우트에 대한 리디렉션을 준비한다.
• 초안이 로그아웃한 방문자에게 계속 접근 불가능한지 검증한다.

새 사이트가 프로덕션에서 성공적으로 운영되고 롤백이 더는 필요하지 않을 때까지 백업과 WordPress 배포를 유지하세요.

문제 해결

XML 파일을 파싱할 수 없음

Tools → Export에서 파일을 다시 내보내고 다운로드가 완료되었는지 확인하세요. 인코딩을 바꾸는 도구로 XML을 편집하지 마세요.

컬렉션이 호환되지 않음으로 표시됨

기존 필드의 슬러그는 같지만 유형이 다릅니다. 다시 시도하기 전에 게시물 유형 매핑을 변경하거나 Content Types에서 필드를 조정하세요. 준비 단계는 누락된 필드를 추가하지만 기존 필드의 유형은 변경하지 않습니다.

미디어 URL 다운로드 실패

원본 첨부 파일이 WordPress 세션 없이 접근 가능한지 확인하세요. 인증 뒤에 있는 미디어, 삭제된 파일, 사설 네트워크 주소로의 리디렉션은 개별적으로 실패하며 미디어 오류 목록에 남습니다.

테마 맞추기

아카이브 라우트에는 getEmDashCollection()을, 슬러그 라우트에는 getEmDashEntry()를 사용하세요. entry.id는 라우트 식별자이며 보통 슬러그입니다. entry.data.id는 관계 헬퍼가 사용하는 저장된 콘텐츠 ID입니다.

다음 라우트는 가져온 게시물을 렌더링합니다.

---
import { decodeSlug, getEmDashEntry } from "emdash";
import { PortableText } from "emdash/ui";

const slug = decodeSlug(Astro.params.slug);
if (!slug) return Astro.rewrite("/404");

const { entry: post, error } = await getEmDashEntry("posts", slug);
if (error) return new Response("Could not load the post", { status: 500 });
if (!post) return Astro.rewrite("/404");
---

<article>
  <h1>{post.data.title}</h1>
  <PortableText value={post.data.content} />
</article>

라우트와 컴포넌트 매핑은 WordPress 테마 포팅을, 엔드포인트 계약과 정확한 재시도 경계는 콘텐츠 가져오기를 참고하세요.