---
url: 'https://dxpr.com/zh-hans/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-24T13:51:43+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-24T13:51:43+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-24T13:51:43+0000'
      dateModified: '2026-10-24T13:51:43+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/zh-hans/hc/documentation/learn-dxpr-builder/getting-started/migration-1x-to-3x'
      articleSection: 从其他构建器迁移
    -
      '@type': WebPage
      '@id': 'https://dxpr.com/zh-hans/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/zh-hans'
      publisher:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
      inLanguage: zh-hans
---
[帮助中心](/zh-hans/node/75)/[文档](/zh-hans/hc/documentation) /[学习 DXPR Builder](/zh-hans/hc/documentation/learn-dxpr-builder) /[从这里开始](/zh-hans/hc/documentation/learn-dxpr-builder/start-here) /[从其他构建器迁移](/zh-hans/hc/documentation/learn-dxpr-builder/migration) # 从 DXPR Builder 1.x 或 2.x 迁移.

 学习 DXPR Builder从这里开始从其他构建器迁移

   ## 本指南内容

 相关指南

- [更新 DXPR Builder](/zh-hans/hc/documentation/learn-dxpr-builder/getting-started/updating)
- [更新日志](/zh-hans/hc/documentation/learn-dxpr-builder/getting-started/changelog)
- [配置参考](/zh-hans/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 | 模块机器名 `dxpr_builder` 自 2020 年 5 月首个 1.x 起。最后版本 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（`dxpr_builder.info.yml` 中的 `core_version_requirement`）。
- Key 模块。3.x 硬依赖；`drush updatedb` 发现缺失时 `dxpr_builder_update_9020()` 安装它。
- DXPR Builder 2.0.0 及以上签发的产品密钥。没有 `dxpr_tier` 声明的密钥被设置表单拒绝。
- 提供 Bootstrap 5 的主题，或 **Bootstrap 5** sideload 选项。Bootstrap 3 和 4 的 sideload 已取消。

## 迁移步骤

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` 并检查 **License** 分区。更新 9020 后 **Storage method** 为 **Key module**，**Key** 为 `DXPR Builder JWT`（`dxpr_builder_jwt`）。
5. 在同一页面检查 **Sideload Bootstrap files**。之前选 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 来时运行）

| 钩子 | What it does |
|---|---|
| 8026 | 更新 DXPR Builder 中央用户存储。 |
| 8027 | 添加许可证信息区块，并在 People 视图加 "DXPR Builder User" 列。 |
| 8028 | 创建内容锁定的 `dxpr_lock` 表。 |
| 8029 | 在用户许可证仪表盘添加许可证区块。 |
| 8030 | "Bootstrap 3 Light" 选项移除后切换 Bootstrap 设置。 |
| 8031 | 在禁用安装处启用许可证信息区块。 |
| 8032 | 从许可证存储移除被封禁用户。 |
| 8033 | 初始化 `drm_last_contact`。 |
| 8034 | 安装 `dxpr_user_is_disavowed` 用户字段和 avow/disavow 用户操作。 |
| 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 Assistant 和 AI Tone of Voice 按钮。 |
| 9012 | 恢复 `ai_page_enabled`，默认 true。 |
| 9013 | 设置 AI 输出过滤默认值（`ai_output_allowed_domains`）。 |
| 9015 | 添加 `ai_image_enabled`，默认 true。 |

### 3.x 新增（从 1.x 或 2.x 来时运行）

| 钩子 | What it does |
|---|---|
| 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`）和状态报告列出待迁移内容。上面的更新钩子迁移它，该页的 **Run now** 和 **Run all pending migrations** 操作也迁移。迁移是带 `dxpr_builder.content_migration` 标签的服务（`dxpr_builder.services.yml`）。记录失败的批次不标记完成；失败项记入日志并保持待迁移。

1.x 和 2.x 在渲染时应用的 `glazed_to_dxpr` 字符串改写已移除。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()` | 已移除；无替代钩子。 |
| 无 | `hook_dxpr_builder_icon_sets_alter(array &$icon_sets)`，新增。图标集在 `MODULE.dxpr_icon_sets.yml` 文件中声明。 |

### CSS 与实用类

定位 Glazed 类名的自定义 CSS 必须改用 DXPR 名称，如 `dxpr-theme-util`、`panel-dxpr` 和 `dxpr-builder`。编辑器暴露的实用类通过 `hook_dxpr_builder_classes_alter()` 提供。

### 配置与部署

- 从任何已提交配置中移除 `json_web_token`；更新 9020 后密钥在 `dxpr_builder_jwt` Key 实体中。该 Key 使用 **Configuration** 提供者，因此密钥仍导出为 `key.key.dxpr_builder_jwt`。请将它切换为 **File** 或 **Environment** 提供者（`/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` 启用 sideload。

## What's next?

- [更新](/hc/documentation/learn-dxpr-builder/getting-started/updating)：系列内的常规更新
- [更新日志](/hc/documentation/learn-dxpr-builder/getting-started/changelog)：每个版本改了什么
- [配置参考](/zh-hans/hc/documentation/learn-dxpr-builder/reference/config-reference)：更新钩子涉及的每个键