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

EmDash는 WordPress에서의 완전한 마이그레이션 경로를 제공합니다. CLI 없이 관리 대시보드에서 글, 페이지, 미디어, 택소노미를 가져올 수 있습니다.

시작하기 전에

콘텐츠 보내기

WordPress에서 도구 → 보내기로 전체보내기 파일(.xml)을 다운로드합니다.

사이트 백업

마이그레이션이 성공했는지 확인할 때까지 WordPress 사이트를 계속 운영합니다.

가져오기 방법

EmDash는 WordPress 콘텐츠 가져오기를 세 가지 방식으로 지원합니다.

방법	적합한 경우	초안 포함	인증 필요
WXR 파일 업로드	완전한 마이그레이션	예	아니오
WordPress.com	WordPress.com에 호스팅된 사이트	예	OAuth
REST API(프로브)	보내기 전 콘텐츠 확인	아니오	선택

대부분의 마이그레이션에는 WXR 파일 업로드를 권장합니다. 초안, 사용자 정의 필드, 비공개 글을 포함한 모든 콘텐츠를 가져옵니다.

WXR 파일 가져오기

WordPress에서 보내기

WordPress 관리자에서 도구 → 보내기 → 모든 콘텐츠 → 보내기 파일 다운로드.
가져오기 마법사 열기

EmDash에서 관리 → 설정 → 가져오기 → WordPress.
보내기 파일 업로드

.xml 파일을 끌어다 놓거나 찾아보기. 브라우저에서 파싱됩니다.

감지된 콘텐츠 검토

마법사에 다음과 같이 표시됩니다:

Found in export:
├── Posts: 127 → posts [New collection]
├── Pages: 12  → pages [Add fields]
└── Media: 89 attachments

매핑 구성

가져올 글 유형을 선택합니다. EmDash가 자동으로:
- 매핑되지 않은 글 유형에 새 컬렉션 생성
- 기존 컬렉션에 누락된 필드 추가
- 필드 유형 충돌 경고
가져오기 실행

콘텐츠 가져오기를 클릭합니다. 항목별로 진행 상황이 표시됩니다.
미디어 가져오기(선택)

콘텐츠 이후 미디어 파일 다운로드 여부를 선택합니다. EmDash는:
- WordPress URL에서 다운로드
- 콘텐츠 해시로 중복 제거
- 콘텐츠의 URL을 자동으로 다시 씀

콘텐츠 변환

Gutenberg → Portable Text

EmDash는 Gutenberg 블록을 Portable Text로 변환합니다.

Gutenberg 블록	Portable Text	참고
`core/paragraph`	`block` style=“normal”	인라인 마크 유지
`core/heading`	`block` style=“h1-h6”	블록 속성에서 레벨
`core/image`	`image` 블록	미디어 참조 업데이트
`core/list`	`listItem` 유형의 `block`	순서 있음/없음 목록
`core/quote`	`block` style=“blockquote”	인용 포함
`core/code`	`code` 블록	언어 속성 유지
`core/embed`	`embed` 블록	URL과 제공자 저장
`core/gallery`	`gallery` 블록	이미지 참조 배열
`core/columns`	`columns` 블록	중첩 콘텐츠 유지
알 수 없는 블록	`htmlBlock`	검토용 원시 HTML

알 수 없는 블록은 원본 HTML과 블록 메타데이터와 함께 htmlBlock으로 저장됩니다. 수동으로 변환하거나 사용자 정의 Portable Text 컴포넌트로 렌더링할 수 있습니다.

클래식 에디터 콘텐츠

클래식 에디터의 HTML은 Portable Text 블록으로 변환됩니다. 인라인 스타일(<strong>, <em>, <a>)은 span의 마크가 됩니다.

상태 매핑

WordPress 상태	EmDash 상태
`publish`	`published`
`draft`	`draft`
`pending`	`pending`
`private`	`private`
`future`	`scheduled`
`trash`	`archived`

택소노미 가져오기

카테고리와 태그는 계층이 유지된 채 택소노미로 가져옵니다:

WordPress:                    EmDash:
├── Categories (hierarchical) ├── taxonomies table
│   ├── News                  │   ├── category/news
│   │   ├── Local             │   ├── category/local (parent: news)
│   │   └── World             │   ├── category/world (parent: news)
│   └── Sports                │   └── category/sports
└── Tags (flat)               └── content_taxonomies junction
    ├── featured                  ├── tag/featured
    └── breaking                  └── tag/breaking

사용자 정의 필드 및 ACF

글 메타와 ACF 필드는 가져오기 중 분석됩니다:

분석 단계

마법사가 사용자 정의 필드를 감지하고 EmDash 필드 유형을 제안합니다:

Custom Fields:
├── subtitle (string, 45 posts)
├── _yoast_wpseo_title → seo.title (string, 127 posts)
├── _thumbnail_id → featuredImage (reference, 89 posts)
└── price (number, 23 posts)

필드 매핑

_edit_, _wp_로 시작하는 내부 필드는 기본적으로 숨겨집니다. SEO 플러그인 필드는 seo 객체로 매핑됩니다.
유형 추론

EmDash는 값에서 유형을 추론합니다:
- 숫자 문자열 → number
- "1", "0", "true", "false" → boolean
- ISO 날짜 → date
- 직렬화된 PHP/JSON → json
- WordPress ID(예: _thumbnail_id) → reference

URL 리다이렉트

가져온 후 EmDash는 리다이렉트 맵을 생성합니다:

{
	"redirects": [
		{ "from": "/?p=123", "to": "/posts/hello-world" },
		{ "from": "/2024/01/hello-world/", "to": "/posts/hello-world" },
		{ "from": "/category/news/", "to": "/categories/news" }
	],
	"feeds": [
		{ "from": "/feed/", "to": "/rss.xml" },
		{ "from": "/feed/atom/", "to": "/atom.xml" }
	]
}

다음에 적용할 수 있습니다:

Cloudflare 리다이렉트 규칙
호스팅 플랫폼의 리다이렉트 설정
astro.config.mjs의 Astro redirects 옵션

개념 매핑 참고

WordPress 패턴을 EmDash에 맞출 때 참고하세요.

WordPress	EmDash	참고
`register_post_type()`	관리 UI의 컬렉션	대시보드 또는 API로 생성
`register_taxonomy()`	택소노미 또는 배열 필드	복잡도에 따라
`register_meta()`	컬렉션 스키마의 필드	타입 지정, 키-값 아님
`WP_Query`	`getCollection(filters)`	런타임 쿼리
`get_post()`	`getEntry(collection, id)`	항목 또는 null
`wp_insert_post()`	`POST /_emdash/api/content/{type}`	REST API
`the_content`	`<PortableText value={...} />`	Portable Text 렌더링
`add_shortcode()`	Portable Text 사용자 정의 블록	사용자 정의 렌더러
`register_block_type()`	Portable Text 사용자 정의 블록	숏코드와 동일
`add_menu_page()`	플러그인 관리 페이지	`/_emdash/admin/` 하위
`add_action/filter()`	플러그인 훅	`hooks.content:beforeSave` 등
`wp_options`	`ctx.kv`	키-값 저장소
`wp_postmeta`	컬렉션 필드	구조화됨
`$wpdb`	`ctx.storage`	직접 스토리지 접근
카테고리/태그	택소노미	계층 유지

API 가져오기(고급)

WordPress 가져오기는 관리 대시보드와 REST API로 사용할 수 있습니다. 필드 매핑, 충돌 해결, 진행 추적에는 마법사 사용을 권장합니다.

프로그래밍 접근은 /_emdash/api/import/wordpress/ 엔드포인트를 사용합니다.

문제 해결

”XML parsing error”

보내기 파일이 손상되었거나 불완전할 수 있습니다. WordPress에서 다시 보내세요.

미디어 다운로드 실패

인증 뒤에 있거나 URL이 바뀐 이미지가 있을 수 있습니다. 가져오기는 계속되며 실패한 URL은 기록됩니다.

필드 유형 충돌

기존 컬렉션에 호환되지 않는 유형의 필드가 있으면 마법사가 충돌을 표시합니다. 다음 중 하나:

EmDash 필드 이름 변경
WordPress 필드 매핑 변경
컬렉션 삭제 후 재생성

대용량보내기

100MB를 넘으면:

WordPress에서 글 유형별로 나누어보내기
파일을 순서대로 가져오기
안정성을 위해 --resume이 있는 CLI 사용

다음 단계

Content Import — 기타 가져오기 소스 및 방법
Plugin Porting — WordPress 플러그인 기능 이전
Working with Content — 가져온 콘텐츠 조회 및 렌더링