WordPress에서 마이그레이션 | EmDash CMS Everything

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

시작하기 전에

다음 항목을 준비하세요.

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

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

가져오기 방법 선택

방법	사용하는 경우	포함되는 데이터
WXR 업로드	Tools → Export에서 내보낼 수 있을 때	내보내기에 포함된 데이터. 게시물, 페이지, 사용자 정의 게시물 유형, 택소노미 용어, 재사용 가능한 블록, 작성자, 첨부 파일 URL을 포함합니다
EmDash Exporter	WordPress 사이트를 직접 관리하며 Exporter를 설치할 수 있을 때	인증이 필요한 콘텐츠와 함께 지원되는 사이트 설정, SEO 필드, 택소노미, 미디어 메타데이터. Exporter 1.2.0 이상에서는 댓글, 메뉴, 로고, 파비콘도 포함

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

WXR 파일 내보내기

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

EmDash Exporter 연결

WordPress Plugins 화면에서 Exporter 버전을 확인합니다. 댓글, 메뉴, 로고, 파비콘에는 Exporter 1.2.0 이상이 필요합니다. 이전 버전에서는 이 항목 없이 가져오기가 완료되며, 누락되었다고 알려 주지 않습니다.

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

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

관리자에서 가져오기

관리자 사이드바에서 Import를 선택해 Import from WordPress 페이지를 열거나, /_emdash/admin/import/wordpress로 바로 이동합니다.
WXR 파일을 업로드하거나, Exporter 마이그레이션 키를 붙여 넣거나, WordPress URL을 입력합니다.
분석 결과를 검토합니다. WordPress 게시물 유형마다 대상 컬렉션, 필수 필드, 기존 필드와의 호환성을 확인합니다.
WordPress 작성자를 EmDash 사용자에 매핑합니다. 매핑되지 않은 원본 작성자는 게스트 byline으로 표현할 수 있으므로, 표시되는 작성자 크레딧이 EmDash 로그인 권한 부여 여부에 좌우되지 않습니다.
Exporter로 가져올 때는 메뉴, 사이트 제목과 태그라인, 로고와 파비콘, 지원되는 SEO 값을 가져올지 선택합니다. 이 스위치는 WXR 경로에는 포함되지 않습니다.
가져오기를 시작합니다. EmDash는 항목을 만들기 전에 누락된 호환 컬렉션과 필드를 먼저 만듭니다.
첨부 파일이 발견되었다면 미디어 단계를 실행합니다. EmDash는 원본 바이트 데이터를 다운로드하고, 구성된 스토리지 어댑터를 통해 저장하며, 일치하는 콘텐츠 URL을 다시 작성합니다.

변환 동작

상태

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

WordPress	EmDash
`publish`	`published`
`draft`	`draft`
`pending`	`draft`
`private`	`draft`
`future`, `trash` 또는 알 수 없는 상태	`draft`

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

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

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

WordPress가 서버에서 렌더링하는 블록(Latest Posts나 플러그인이 제공하는 블록 등)에는 저장된 마크업이 없습니다. 이런 블록은 원래 블록 주석이 담긴 HTML 블록으로 가져옵니다. 예: . 이 블록은 사이트에 아무 콘텐츠도 표시하지 않습니다. 편집기에서 블록의 HTML 탭을 열어 원래 무엇이었는지 확인한 다음, 다시 만들거나 제거하세요.

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

컬렉션과 필드

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

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

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

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

EmDash Exporter 경로는 대상 컬렉션에 일치하는 필드가 있으면 사용자 정의 메타와 Advanced Custom Fields(ACF) 값을 복사할 수 있습니다. ACF 필드 그룹에 “Post Type is equal to” 위치 규칙이 있으면, 분석은 그룹의 모든 ACF 필드에 대해 필드를 제안합니다. 텍스트, 숫자, 참/거짓 필드는 대응하는 유형이 되고, select, checkbox, repeater, group, relationship처럼 목록이나 객체를 담을 수 있는 필드는 JSON 필드가 됩니다. 다른 위치 규칙으로 할당된 그룹의 필드는 Exporter가 보고하는 메타 키에서만 제안됩니다. 이전 가져오기가 메타 키로 필드를 만든 컬렉션은 해당 필드를 그대로 유지하므로, 리피터는 행과 하위 필드마다 필드 하나씩으로 들어옵니다. JSON 값은 WordPress의 형태를 유지합니다. relationship, post object, user, taxonomy 필드는 EmDash 항목이 아니라 WordPress ID로 WordPress 글, 사용자, 용어를 가리키며, 이미지, 파일, 갤러리 필드는 가져온 EmDash 미디어가 아니라 WordPress 미디어 파일을 가리킵니다. 둘 이상의 글에 저장된 ACF 그룹 하위 필드는 그룹의 JSON 필드 옆에 별도의 필드로 나타날 수도 있으니, 템플릿에서 사용하는 쪽을 남기세요. 이 값들은 템플릿에서 사용하기 전에 검토하세요.

Exporter 경로는 해당 가져오기 스위치가 켜져 있으면 지원되는 대표 이미지와 Yoast 또는 Rank Math SEO 필드를 만들고 값을 채울 수도 있습니다.

작성자와 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에서 필드를 조정하세요. 준비 단계는 누락된 필드를 추가하지만 기존 필드의 유형은 변경하지 않습니다.

봇 방어가 Exporter를 차단함

Cloudflare의 봇 방어가 Exporter API 대신 챌린지 페이지로 EmDash의 요청에 응답할 수 있습니다. 그러면 EmDash는 봇 방어가 연결을 차단했다고 보고합니다. 마이그레이션하는 동안에는 Exporter 요청을 통과시키세요.

Super Bot Fight Mode나 다른 Cloudflare WAF 기능을 사용한다면 Skip 동작의 사용자 지정 규칙을 추가하고, 챌린지를 발행하는 모든 규칙보다 위에 두세요. All Super Bot Fight Mode rules를 선택하고, 영역이 I’m Under Attack 모드를 사용한다면 Security Level도 선택합니다. 다음 표현식은 사용자 친화적 퍼머링크 사용 여부와 관계없이, 하위 디렉터리에 설치된 WordPress를 포함해 Exporter API와 일치하며, EmDash가 다운로드하는 미디어 파일과도 일치합니다.
```
(http.request.uri.path contains "/wp-json/emdash/v1/")
or (http.request.uri.query contains "rest_route=%2Femdash%2Fv1%2F")
or (http.request.uri.path contains "/wp-content/uploads/")
```
Cloudflare Free 요금제의 Bot Fight Mode는 규칙으로 건너뛸 수 없습니다. 마이그레이션 중에는 끄고 끝나면 다시 켜세요.

미디어 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 테마 포팅을, 엔드포인트 계약과 정확한 재시도 경계는 콘텐츠 가져오기를 참고하세요.