# @directus-labs/migration-bundle 中文文档

规范地址：https://npmcn.com/package/%40directus-labs/migration-bundle/

版本：1\.2\.0
npm 元数据更新时间：2026-06-05T15:48:27.317Z
中文译文更新时间：2026-11-13T04:01:30.658Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40directus-labs/migration-bundle
原文对照：https://npmcn.com/package/%40directus-labs/migration-bundle/?lang=original
项目主页：https://github.com/directus-labs/extensions#readme
源码仓库：https://github.com/directus-labs/extensions

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：532 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：9 个
- 首次发布：2025-03-06T09:53:39.224Z
- 最新版本发布：2026-03-03T16:11:26.730Z
- 近 30 天下载量：2336（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 1 个）

## 中文简介

从当前源 Directus 实例移到另一个目标 Directus 实例 .

## 安装

```sh
npm install @directus-labs/migration-bundle
```

也可以使用：`pnpm add @directus-labs/migration-bundle`、`yarn add @directus-labs/migration-bundle`、`bun add @directus-labs/migration-bundle`

## README

# Directus 迁移模块

使用这个简单的模块,将当前 Directus 实例轻松地移到另一个位置.

![Migration Module Banner](https://raw.githubusercontent.com/directus-labs/extensions/main/packages/migration-bundle/docs/migration-module.jpg)

## 使用量

一旦安装, 您可以启用工程设置中的导航菜单项, 或者直接到模块页面 `/admin/migration`。 。 。 .

要启动, 请输入目的地 URL 和 管理令牌到提供的字段, 然后单击 **检查**。这将比较两个Directus平台,看看它们是否兼容.

_请确保目标实例与源实例在同一版本和同一数据库平台上._

如果有效,可以立即启动"干跑"迁移,或者根据需要定制迁移.

取消检查 Dry Run 复选框并点击启动来运行迁移 。 进程在背景中运行, 这样您就可以关闭您的浏览器, 当迁移完成后它会通知您 。 通常,中小型项目只需一至二分钟。 大型文件库的项目需要更长的时间.

![Migration Live Updates](https://raw.githubusercontent.com/directus-labs/extensions/main/packages/migration-bundle/docs/migration-module-live-updates.jpg)

### 不可调和的Schema

目的地实例必须与源实例相同并具有相同的数据库平台. 使用 **强制** 当此错误发生时出现的复选框.

不建议这样做,很可能需要进一步干预.

### 迁移失败

如果移民失败了,别担心,只要再管理移民. 现有内容被跳过,所以它会继续下去.

## 所需资源

-   2x Directus 例在至少11.1.2+上使用同一数据库平台.
-   管理用户和来自目的地的管理令牌.

_对于较大的项目,迁移自然会使用显著的带宽. API的电话被限制,以确保目的地不会不堪重负._

## 安装

关于从市场安装或人工安装扩展的详情,请参考《官方指南》.

## 配置

### 混合配置系统

迁移模块采用将环境变量和Directus预设相结合的两级配置系统,以达到最大灵活性.

### 1\. 环境变量(默认)

管理员可以通过环境变量设置适用于所有用户的默认值:

```bash
# Default destination URL
MIGRATION_BUNDLE_DEFAULT_URL=https://stage.example.com

# Default admin token (optional - can be left empty for security)
MIGRATION_BUNDLE_DEFAULT_TOKEN=your-admin-token

# Default selected options (comma-separated)
MIGRATION_BUNDLE_DEFAULT_OPTIONS=content,users,flows
```

现有备选方案 `MIGRATION_BUNDLE_DEFAULT_OPTIONS`数字 :

-   `content` - 收集及其数据
-   `users` - 用户、角色和权限
-   `comments` - 活动评论
-   `presets` - 用户书签
-   `dashboards` - 透视仪表板
-   `extensions` - 安装的扩展
-   `flows` - 自动化流动

### 2\. Directus 预设(用户配置)

用户可以将其迁移配置保存为Directus预设,这些预设被存储在数据库中,可以在会话和设备中访问.

**特征 :**

-   **命名的配置**: 保存"Production Sync","Content Only","Full migration"等多个配置
-   **范围控制**: 为您自己、 您的角色或全球范围保存预设( 只有管理员)
-   **快速访问**: 从下放菜单上装入已保存的配置
-   **覆盖默认**: 用户预设优先于环境默认

**如何使用 :**

1.  配置您的迁移设置( URL, 令牌, 选项)
2.  单击书签图标 (QQ) 保存为预设
3.  选择名称和范围(个人/作用/全球)
4.  从窗体上方的下拉中装入已保存的预设

### 3\. 配置优先事项

该系统遵循这一优先顺序:

1.  **用户选择的预设** (最高优先级)
2.  **环境默认** (如果没有选择预设)
3.  **空窗体** (如果没有配置)

这种办法规定:

-   **管理员**: 不同环境的特定环境默认值
-   **用户**: 个人已保存配置
-   **为团队**: 通过基于角色的预设共享配置
-   **最佳做法**: 灵活一致的设置

## 如何定制移徙

1.  在迁移模块上,添加目的地服务器和令牌并单击 **检查**
2.  如果有效, 将会出现“ 迁移” 选项字段 。 单击此以显示迁移的内容
3.  取消选中任何章节以排除迁移
4.  开始迁移

### 文件批量大小

当 **内容** 选择范围,a **批量大小** 控制出现。 这控制了在新批开始前将多少文件读入内存并上传.

| 数值 | 行为 |
| --- | --- |
| 页:1 | 内存使用率最低——最适合受限环境 |
| **10个** (默认) | 适用于大多数项目 |
| 15个 | 中等速度提高 |
| 20国 | 在高波段连接上更快 |
| 第25条 | 最大吞吐量——更高的内存使用量 |

**何时调整 :**

-   **降低批量大小** 如果迁移的内存耗尽,或者源/目的地服务器负重.
-   **提高批量大小** 如果您有快速连接并想要加快大型文件库.

![Customise the module](https://raw.githubusercontent.com/directus-labs/extensions/main/packages/migration-bundle/docs/migration-module-customize.jpg)

## 权限

这一扩展要求两个实例的管理员保证所有数据都可获得和可写.

## 常见问题

### @directus-labs/migration-bundle 是什么？

从当前源 Directus 实例移到另一个目标 Directus 实例 \.

### 如何安装 @directus-labs/migration-bundle？

在项目目录运行 npm install @directus-labs/migration-bundle，或使用 pnpm add / yarn add / bun add。

### @directus-labs/migration-bundle 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/directus-labs\_\_migration-bundle 是否存在。

### @directus-labs/migration-bundle 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @directus-labs/migration-bundle 可以商用吗？

@directus-labs/migration-bundle 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @directus-labs/migration-bundle 的下载量有多少？

根据 npm 官方下载统计，@directus-labs/migration-bundle 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,336 次，日均约 78 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @directus-labs/migration-bundle 还在维护吗？

最新版本 1\.2\.0 发布于 2026/03/04（8 个月前）；至今共发布 5 个版本，其中过去 12 个月发布了 1 个；首次发布于 2025/03/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。