---
url: 'https://dxpr.com/ko/hc/documentation/learn-dxpr-builder/getting-started/migration-1x-to-3x'
title: 'DXPR Builder 1.x 또는 2.x에서 마이그레이션 | DXPR'
author:
  name: Jurriaan
  url: 'https://dxpr.com/users/jurriaan'
date: '2026-10-24T14:04:11+00:00'
copyright: 'Copyright DXPR. All rights reserved.'
type: article
summary: 'DXPR Builder 3.x는 모든 1.x나 2.x 릴리스에서 제자리에서 업데이트됩니다. Composer가 코드를 교체하고 drush updatedb가 구성과 콘텐츠를 변환하는 dxpr_builder.install의 업데이트 후크를 실행합니다. 이 페이지에서는 해당 후크의 동작, 사용자 정의 코드의 변경 사항, 결과 확인 방법을 설명합니다. 릴리스 날짜는 git 태그 기준입니다. 이전 릴리스를 참조하세요.'
tags:
  - 'Move from another builder'
image: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg'
published: true
og:
  site_name: DXPR
  updated_time: '2026-10-24T14:04:11+0000'
  'image:alt': 'DXPR, powered by Drupal: AI-powered Drupal for marketers.'
schema:
  '@context': 'https://schema.org'
  '@graph':
    -
      mainEntity: {  }
    -
      '@type': TechArticle
      headline: 'DXPR Builder 1.x 또는 2.x에서 마이그레이션'
      description: 'DXPR Builder 3.x는 모든 1.x나 2.x 릴리스에서 제자리에서 업데이트됩니다. Composer가 코드를 교체하고 drush updatedb가 구성과 콘텐츠를 변환하는 dxpr_builder.install의 업데이트 후크를 실행합니다. 이 페이지에서는 해당 후크의 동작, 사용자 정의 코드의 변경 사항, 결과 확인 방법을 설명합니다. 릴리스 날짜는 git 태그 기준입니다. 이전 릴리스를 참조하세요.'
      image:
        '@type': ImageObject
        url: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg'
        width: '1200'
        height: '630'
      datePublished: '2026-10-24T14:04:11+0000'
      dateModified: '2026-10-24T14:04:11+0000'
      author:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
        url: 'https://dxpr.com/'
        logo:
          '@type': ImageObject
          url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg'
          width: '1348'
          height: '501'
      publisher:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
        url: 'https://dxpr.com/'
        logo:
          '@type': ImageObject
          url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg'
          width: '1348'
          height: '501'
      mainEntityOfPage: 'https://dxpr.com/ko/hc/documentation/learn-dxpr-builder/getting-started/migration-1x-to-3x'
      articleSection: '다른 빌더에서 이전'
    -
      '@type': WebPage
      '@id': 'https://dxpr.com/ko/hc/documentation/learn-dxpr-builder/getting-started/migration-1x-to-3x'
      description: 'DXPR Builder 3.x는 모든 1.x나 2.x 릴리스에서 제자리에서 업데이트됩니다. Composer가 코드를 교체하고 drush updatedb가 구성과 콘텐츠를 변환하는 dxpr_builder.install의 업데이트 후크를 실행합니다. 이 페이지에서는 해당 후크의 동작, 사용자 정의 코드의 변경 사항, 결과 확인 방법을 설명합니다. 릴리스 날짜는 git 태그 기준입니다. 이전 릴리스를 참조하세요.'
      breadcrumb:
        '@type': BreadcrumbList
        itemListElement:
          -
            '@type': ListItem
            position: 1
            name: 홈
            item: 'https://dxpr.com/ko'
      publisher:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
      inLanguage: ko
---
[도움말 센터](/ko/node/75)/[문서](/ko/hc/documentation) /[DXPR Builder 배우기](/ko/hc/documentation/learn-dxpr-builder) /[여기서 시작](/ko/hc/documentation/learn-dxpr-builder/start-here) /[다른 빌더에서 이전](/ko/hc/documentation/learn-dxpr-builder/migration) # DXPR Builder 1.x 또는 2.x에서 마이그레이션.

 DXPR Builder 배우기여기서 시작다른 빌더에서 이전

   ## 이 가이드의 내용

 관련 가이드

- [DXPR Builder 업데이트](/ko/hc/documentation/learn-dxpr-builder/getting-started/updating)
- [변경 로그](/ko/hc/documentation/learn-dxpr-builder/getting-started/changelog)
- [구성 참조](/ko/hc/documentation/learn-dxpr-builder/reference/config-reference)

DXPR Builder 3.x는 모든 1.x나 2.x 릴리스에서 제자리에서 업데이트됩니다. Composer가 코드를 교체하고 `drush updatedb`가 구성과 콘텐츠를 변환하는 `dxpr_builder.install`의 업데이트 후크를 실행합니다. 이 페이지에서는 해당 후크의 동작, 사용자 정의 코드의 변경 사항, 결과 확인 방법을 설명합니다. 릴리스 날짜는 git 태그 기준입니다. [이전 릴리스](/hc/documentation/learn-dxpr-builder/getting-started/changelog-older)를 참조하세요.

## 버전 히스토리 요약

| 시리즈 | Drupal | 참고 |
|---|---|---|
| 7.x-1.x | Drupal 7 | Glazed Builder로 판매되었으며 나중에 이름이 변경됨 |
| 1.x (8.x-1.x) | Drupal 8, 9 | 2020년 5월 첫 1.x 릴리스부터 모듈 머신 이름 `dxpr_builder`. 마지막 릴리스 1.8.8 |
| 2.x | Drupal 9.3~11 | CKEditor 5, Key 모듈 지원, 첫 AI 기능. 마지막 릴리스 2.8.1 |
| 3.x | Drupal 10.2, 11 | Bootstrap 5 전용, Key 모듈 필수, 콘텐츠 마이그레이션, AI 페이지 및 이미지 생성 |

머신 이름은 1.x와 3.x 사이에서 바뀌지 않았습니다. Glazed 시절 마크업이 남아 있는 콘텐츠는 업그레이드 전에 1.x나 2.x에서 마이그레이션해야 합니다. 3.x는 더 이상 Glazed 이름을 재작성하지 않습니다(아래 참조).

## 시작 전 요구 사항

- Drupal 10.2 이상 또는 Drupal 11(`core_version_requirement`는 `dxpr_builder.info.yml`에 있음).
- Key 모듈. 3.x의 하드 종속성이며, `drush updatedb` 실행 시 없으면 `dxpr_builder_update_9020()`이 설치합니다.
- DXPR Builder 2.0.0 이상용으로 발급된 제품 키. `dxpr_tier` 클레임이 없는 키는 설정 양식에서 거부됩니다.
- Bootstrap 5를 제공하는 테마 또는 **Bootstrap 5** 사이드로드 옵션. Bootstrap 3, 4 사이드로드는 더 이상 없습니다.

## 마이그레이션 단계

1. 데이터베이스와 파일을 백업합니다.

    ```bash
    drush sql:dump --result-file=backup.sql

    ```
2. Composer로 코드를 업데이트합니다. 3.x는 현재 사전 릴리스로 게시되므로 허용합니다.

    ```bash
    composer require 'drupal/dxpr_builder:^3.0@beta' --with-all-dependencies

    ```
3. 업데이트 후크를 실행하고 캐시를 다시 빌드합니다.

    ```bash
    drush updatedb
    drush cache:rebuild

    ```

    여러 3.x 후크가 모든 DXPR Builder 필드 값을 일괄 처리합니다(아래 참조). 대규모 사이트에서는 수초가 아니라 수분이 걸립니다.
4. 페이지 `/admin/dxpr_studio/dxpr_builder/settings`를 열고 **라이선스** 섹션을 확인합니다. 업데이트 9020 이후 **저장 방법**은 **Key 모듈**이며 **키**는 `DXPR Builder JWT`(`dxpr_builder_jwt`)입니다.
5. 같은 페이지에서 **Bootstrap 파일 사이드로드**를 확인합니다. Bootstrap 3이나 4가 선택되어 있던 사이트는 이제 **Bootstrap 5**로 설정됩니다.
6. 페이지 `/admin/dxpr_studio/dxpr_builder/ai_settings`를 열고 기본적으로 켜져 있는 세 개의 AI 토글을 그대로 둘지 결정합니다.
7. DXPR Builder를 사용하는 페이지를 방문하여 렌더링과 편집이 정상적인지 확인합니다.

## 업데이트 후크의 동작

후크 8005~8025는 1.x에 포함되었습니다. 1.x 사이트는 8026부터 전부 실행하며, 2.8.0이나 2.8.1 사이트는 8040과 9014부터 실행합니다. 함수 이름은 `dxpr_builder_update_NNNN()`입니다.

### 2.x에 추가됨(1.x에서 가져올 때 실행)

| 후크 | 동작 |
|---|---|
| 8026 | 중앙 DXPR Builder 사용자 저장소를 업데이트합니다. |
| 8027 | 라이선스 정보 블록과 사용자 보기에 “DXPR Builder User” 컬럼을 추가합니다. |
| 8028 | 콘텐츠 잠금용 `dxpr_lock` 테이블을 만듭니다. |
| 8029 | 사용자 라이선스 대시보드에 라이선스 블록을 추가합니다. |
| 8030 | “Bootstrap 3 Light” 옵션이 제거된 뒤 Bootstrap 설정을 전환합니다. |
| 8031 | 비활성화된 상태로 설치된 곳에 라이선스 정보 블록을 활성화합니다. |
| 8032 | 차단된 사용자를 라이선스 저장소에서 제거합니다. |
| 8033 | 항목 `drm_last_contact`를 초기화합니다. |
| 8034 | 항목 `dxpr_user_is_disavowed` 사용자 필드와 승인/비승인 사용자 작업을 설치합니다. |
| 8035 | 설정 `hide_reminders`를 초기화합니다. |
| 8036 | 프로필의 CKEditor 4 툴바 버튼 이름을 CKEditor 5로 마이그레이션합니다. |
| 8037 | 빠른 로딩 이미지용 기본 이미지 스타일을 추가합니다. |
| 8038 | Key 모듈 통합 서비스 등록을 위해 캐시를 지웁니다. |
| 8039 | 불완전한 `image_scale_and_crop` 설정의 이미지 스타일을 복구합니다. |
| 9007 | 기본 용어와 함께 `ai_tone_of_voice`와 `ai_agent_commands` 어휘를 만듭니다. |
| 9008 | 값 `ai_enabled`을 true로 설정하고 기존 `ai_page_enabled` 키를 제거합니다. |
| 9009 | 항목 `drm_last_contact`를 구성에서 상태로 옮깁니다. |
| 9010 | 캐시를 지웁니다. |
| 9011 | 모든 프로필에 AI 어시스턴트와 AI 말투 버튼을 활성화합니다. |
| 9012 | 값 `ai_page_enabled`을 기본값 true로 복원합니다. |
| 9013 | AI 출력 필터링 기본값(`ai_output_allowed_domains`)을 설정합니다. |
| 9015 | 값 `ai_image_enabled`를 기본값 true로 추가합니다. |

### 3.x에 추가됨(1.x 또는 2.x에서 가져올 때 실행)

| 후크 | 동작 |
|---|---|
| 8040 | 값 `bootstrap`을 `bs5`로 정규화합니다. `1`(Bootstrap 3)과 `bs4` 값이 재작성됩니다. |
| 9014 | 일괄: Owl Carousel 마크업을 콘텐츠에서 Bootstrap 캐러셀로 변환합니다(`src/Migration/OwlCarouselMigration.php`). |
| 9016 | 값 `ai_user_model_selection`을 기본값 true로 추가합니다. |
| 9017 | 일괄: circliful 서클 카운터를 Bootstrap 진행 마크업으로 변환합니다(`CircleCounterMigration.php`). |
| 9018 | 일괄: 레거시 진행률 표시줄 마크업을 Bootstrap 진행 구조로 변환합니다(`ProgressBarMigration.php`). |
| 9020 | Key 모듈을 설치하고 `json_web_token`을 Key 엔티티 `dxpr_builder_jwt`로 옮기며, `api_key_storage`를 `key`로 설정하고 평문 값을 지웁니다. |
| 9021 | 사용자 템플릿의 `type` 속성을 마크업에서 백필합니다. |
| 9022 | 일괄: 내부 `/node/N` 링크에 `data-entity-type`과 `data-entity-uuid`를 추가합니다(`EntityLinkMigration.php`). |
| 9023 | 일괄: 업데이트 9022가 `text_with_summary` 필드에서 손실한 텍스트 형식, 요약, 삭제된 델타를 복구합니다. |
| 9024 | 일괄: 별칭 지정된 내부 링크를 9022와 같은 방식으로 보강합니다(`AliasLinkMigration.php`). |
| 9025 | 존재하지 않는 어휘를 가리키는 `tone_of_voice_vocabulary`를 지웁니다. |
| 9026 | 키가 Key 엔티티에 있는데 설정에 남아 있는 평문 `json_web_token`을 지웁니다. |

업데이트 9019는 없습니다.

### 콘텐츠 마이그레이션

3.x는 콘텐츠 마이그레이션을 일괄 방식으로만 실행합니다. 렌더링 시 변환은 더 이상 없습니다. 마이그레이션 상태 페이지(`/admin/dxpr_studio/dxpr_builder/migration-status`)와 상태 보고서에 대기 중인 콘텐츠가 나열됩니다. 위의 업데이트 후크가 마이그레이션하며, 해당 페이지의 **지금 실행** 및 **모든 대기 마이그레이션 실행** 작업도 마찬가지입니다. 마이그레이션은 `dxpr_builder.content_migration` 태그가 지정된 서비스입니다(`dxpr_builder.services.yml`). 실패를 기록한 일괄 작업은 완료로 표시되지 않으며, 실패한 항목은 로그에 기록되고 대기 상태로 남습니다.

항목 `glazed_to_dxpr` 문자열 재작성은 1.x와 2.x가 렌더링 시 적용하던 것으로, 제거되었습니다. Glazed 이름은 2020년 5월 1.0.0에서 삭제되었으며, 모든 Glazed 및 Carbide 시절 콘텐츠는 해당 릴리스에서 마이그레이션된 것으로 간주됩니다. 재작성은 단순 문자열 치환이었습니다. Glazed를 단순히 언급하는 콘텐츠(지원 문서, 문서 링크)가 있는 사이트에서는 마크업을 마이그레이션하는 대신 본문을 다시 쓰고 링크를 깨뜨렸을 것입니다. 저장된 콘텐츠에 Glazed 클래스 이름이 남아 있는 사이트는 먼저 2.x 릴리스를 실행해야 합니다.

## 사용자 정의 코드의 변경 사항

### 필드 포매터

필드 포매터 ID는 `dxpr_builder_text`(라벨 “DXPR Builder”, `src/Plugin/Field/FieldFormatter/DxprBuilderFormatter.php`)이며 1.x부터 바뀌지 않았습니다. 설정은 `profile` 하나뿐이며, 역할 기반 기본값은 비어 있고 프로필 ID를 사용합니다. 모든 빌더 필드의 뷰 디스플레이에 여전히 이 포매터가 사용되는지 확인합니다. 업데이트 9023의 복구는 해당 필드로 제한됩니다.

### 후크

`dxpr_builder.api.php`에 3.x 후크가 문서화되어 있습니다. Glazed Builder 후크는 다음과 같이 이름을 바꿉니다.

| Glazed Builder 후크 | DXPR Builder 3.x 후크 |
|---|---|
| `hook_glazed_builder_classes()` | `hook_dxpr_builder_classes_alter(array &$dxpr_builder_classes)` |
| `hook_glazed_builder_buttons_folders()` | `hook_dxpr_builder_element_buttons_folders_alter(array &$dxpr_element_buttons_folders)` |
| `hook_glazed_builder_elements_folders()` | 제거됨. 대체 후크 없음. |
| none | `hook_dxpr_builder_icon_sets_alter(array &$icon_sets)`, 신규. 아이콘 세트는 `MODULE.dxpr_icon_sets.yml` 파일에 선언됩니다. |

### CSS 및 유틸리티 클래스

Glazed 클래스 이름을 대상으로 하는 사용자 정의 CSS는 `dxpr-theme-util`, `panel-dxpr`, `dxpr-builder` 같은 DXPR 이름을 사용해야 합니다. 에디터에 노출되는 유틸리티 클래스는 `hook_dxpr_builder_classes_alter()`를 통해 제공됩니다.

### 구성 및 배포

- 항목 `json_web_token`을 커밋된 구성에서 제거합니다. 업데이트 9020 이후 키는 `dxpr_builder_jwt` Key 엔티티에 저장됩니다. 해당 Key는 **구성** 공급자를 사용하므로 키는 여전히 `key.key.dxpr_builder_jwt`로 내보내집니다. 제외하려면 **파일** 또는 **환경** 공급자로 `/admin/config/system/keys`에서 전환합니다.
- 구성 내보내기에 두 개의 AI 어휘와 용어가 포함됩니다.
- 프로필은 `inline_buttons`와 `modal_buttons`에 CKEditor 5 버튼 이름을 내보냅니다.

## 문제 해결

업데이트 후 콘텐츠가 올바르게 표시되지 않는 경우:

1. 명령 `drush cache:rebuild`를 실행합니다.
2. 항목 `/admin/reports/dblog`에서 `dxpr_builder` 채널의 메시지를 확인합니다. 일괄 마이그레이션은 건너뛴 항목을 로그에 기록합니다.
3. 각 빌더 필드의 뷰 디스플레이에 여전히 **DXPR Builder** 포매터가 사용되는지 확인합니다.
4. 테마가 Bootstrap 5를 로드하는지 확인하거나 `/admin/dxpr_studio/dxpr_builder/settings`에서 사이드로드를 활성화합니다.

## 다음 단계

- [업데이트](/hc/documentation/learn-dxpr-builder/getting-started/updating): 시리즈 내 정기 업데이트
- [변경 로그](/hc/documentation/learn-dxpr-builder/getting-started/changelog): 각 릴리스의 변경 사항
- [구성 참조](/hc/documentation/learn-dxpr-builder/reference/config-reference): 업데이트 후크가 건드리는 모든 키