# 数据导入

> Source: https://strapi.nodejs.cn/cms/features/data-management/import

🌐 Data import

`strapi import` 命令用于从加密或压缩的存档中恢复项目数据，包括内容、配置、文件和模式。它支持从 `.tar.gz.enc` 文件或解压目录导入，并提供排除或包含特定数据类型的选项。

🌐 The `strapi import` command restores project data from an encrypted or compressed archive, including content, configuration, files, and schemas. It supports importing from `.tar.gz.enc` files or unpacked directories, with options to exclude or include specific data types.

`strapi import` 命令是 [数据管理功能](/cms/features/data-management) 的一部分，用于从文件或目录导入数据。默认情况下，`strapi import` 命令从加密和压缩的 `tar.gz.enc` 文件中导入数据，该文件包括：

🌐 The `strapi import` command is part of the [Data Management feature](/cms/features/data-management) and used to import data from a file or directory. By default, the `strapi import` command imports data from an encrypted and compressed `tar.gz.enc` file which includes:

- 项目配置，
- 实体：你所有的内容，
- 链接：你实体之间的关系，
- 资源：存储在上传文件夹中的文件，
- schemas,
- `metadata.json` 文件。

该归档文件的结构与 [`strapi export`](/cms/features/data-management/export) 生成的相同：一个 `.tar`，里面包含 `configuration`、`entities`、`links` 和 `schemas` 文件夹，文件夹中充满了编号的 [JSON lines](https://jsonlines.org/) 文件。压缩（`.gz`）和加密（`.enc`）可通过文件扩展名检测，所以普通的 `.tar` 也可以导入。你也可以将 `-f` 指向一个已解包的导出目录（见 [从目录导入](#import-from-a-directory)）。

以下文档详细说明了自定义数据导入的可用选项。导入命令及所有可用选项均通过 [Strapi CLI](/cms/cli#strapi-import) 运行。

🌐 The following documentation details the available options to customize your data import. The import command and all of the available options are run using the [Strapi CLI](/cms/cli#strapi-import).

:::warning

- `strapi import` 在导入备份文件之前，会删除所有现有数据，包括数据库和上传目录。
- 源模式和目标模式必须匹配才能成功使用 `strapi import`，这意味着所有内容类型必须完全相同。
- 恢复的数据不包括 `Admin users` 表，这意味着在恢复的实例中 `createdBy` 和 `updatedBy` 是空的。
- 如果你正在使用云存储提供商（例如 Cloudinary、AWS S3、Azure Blob Storage、Google Cloud Storage），在导入过程中其数据库记录被删除的任何媒体文件可能会通过其删除 API 从云提供商中被永久删除。这会影响所有共享相同云存储账户的环境。为了避免远程资源的意外删除，请确保每个环境使用独立的存储桶/账户。

:::

## 了解导入档案 {#understand-the-import-archive}

🌐 Understand the import archive

`strapi import` 期望一个与 [strapi export 命令](/cms/features/data-management/export#understand-the-exported-archive) 生成的相同平面结构的归档文件：

- `configuration/`：项目配置文件
- `entities/`：实体记录
- `links/`：实体之间的关系
- `schemas/`：模式定义
- `metadata.json`：关于导出的元数据

每个文件夹包含一个或多个 `.jsonl` ([JSON lines](https://jsonlines.org/)) 文件，每一行代表一条记录。这个格式允许你在重新导入之前编辑或转换数据。

### 资源元数据验证 {#asset-metadata-validation}

🌐 Asset metadata validation

每个在 `assets/uploads` 下的文件都会附带一个在 `assets/metadata` 下的元数据侧车。在处理目标之前，`strapi import` 会检查以下内容：

🌐 Every file under `assets/uploads` ships with a metadata sidecar under `assets/metadata`. Before touching the destination, `strapi import` checks the following:

- 每个在 `assets/uploads` 下的上传都有一个对应的 sidecar 在 `assets/metadata` 下
- 每个边车都包含有效的 JSON
- 每个 sidecar 描述的是一个 JSON 对象，而不是列表、字符串或 `null`
- 每个 sidecar 都会声明资源恢复所需的字段
- 每个旁车文件中记录的文件名都与旁车所附的上传文件名称相符

任何未通过这些检查的归档都会在现有数据备份或删除之前被拒绝，所以目标位置保持原样，解决方法是重新生成一个导出文件。这是一次预检，而不是修复：Strapi 不会重建缺失的元数据，也不会通过文件名或哈希匹配资源。

🌐 An archive that fails any of these checks is rejected before the existing data is backed up or deleted, so the destination is left exactly as it was and the fix is to produce a new export. This is a preflight check, not a repair: Strapi does not reconstruct missing metadata or match assets by filename or hash.

当资源被排除在导入之外时，无论是使用 `--exclude files` 还是使用将其排除的 `--only` 列表，检查都会被跳过。

🌐 The check is skipped when assets are excluded from the import, either with `--exclude files` or with an `--only` list that leaves them out.

要准备存档以供手动审核或修改：

🌐 To prepare an archive for manual review or modification:

```bash
yarn strapi export --no-encrypt --no-compress -f my-export
tar -xf my-export.tar
```

```bash
npm run strapi export -- --no-encrypt --no-compress -f my-export
tar -xf my-export.tar
```

在调整 `.jsonl` 文件后，重新创建归档（`tar -cf my-export.tar configuration entities links schemas metadata.json`）并使用 `strapi import -f my-export.tar` 导入。加密和压缩将根据文件扩展名自动检测。

🌐 After adjusting the `.jsonl` files, re‑create the archive (`tar -cf my-export.tar configuration entities links schemas metadata.json`) and import it with `strapi import -f my-export.tar`. Encryption and compression are detected automatically based on the file extension.

## 从目录导入 {#import-from-a-directory}

🌐 Import from a directory

你可以传入一个解压后的导出目录的路径，而不是 `.tar` 压缩档案。这个目录必须包含由 [`strapi export --format dir`](/cms/features/data-management/export#export-to-a-directory) 生成的相同结构（`metadata.json`、`schemas/`、`entities/`、`links/`、`configuration/`，可选 `assets/`）。从目录导入时，系统会自动跳过加密和压缩。

🌐 Instead of a `.tar` archive, you can pass the path to an unpacked export directory. The directory must contain the same layout produced by [`strapi export --format dir`](/cms/features/data-management/export#export-to-a-directory) (`metadata.json`, `schemas/`, `entities/`, `links/`, `configuration/`, and optionally `assets/`). Encryption and compression are skipped automatically when importing from a directory.

```bash
yarn strapi import -f ./my-export
```

```bash
npm run strapi import -- -f ./my-export
```

Strapi 检测到该路径是一个目录，并直接读取数据文件，而不是解压归档文件。

🌐 Strapi detects that the path is a directory and reads the data files directly instead of extracting an archive.

## 指定导入文件 {#specify-the-import-file}

🌐 Specify the import file

要将数据导入到 Strapi 实例中，请在目标项目根目录中使用 `strapi import` 命令。使用 `-f` 或 `--file` 选项指定要导入的文件或目录。对于归档导入，需要提供文件名、扩展名和路径。如果文件已加密，在导入开始之前会提示输入加密密钥。对于目录导入，请传递导出目录的路径（参见 [从目录导入](#import-from-a-directory)）。

🌐 To import data into a Strapi instance, use the `strapi import` command in the destination project root directory. Specify the file or directory to be imported using the `-f` or `--file` option. For archive imports, the filename, extension, and path are required. If the file is encrypted, you are prompted for the encryption key before the import starts. For directory imports, pass the path to the export directory (see [Import from a directory](#import-from-a-directory)).

### 示例：在 Strapi 项目根目录中从文件导入数据的最小命令 {#example-minimum-command-to-import-data-from-a-file-in-the-strapi-project-root}

🌐 Example: Minimum command to import data from a file in the Strapi project root

```bash
yarn strapi import -f /path/to/my/file/export_20221213105643.tar.gz.enc
```

```bash
npm run strapi import -- -f /path/to/my/file/export_20221213105643.tar.gz.enc
```

### 示例：导入一个普通的 `.tar` 存档 {#example-import-a-plain-tar-archive}

🌐 Example: Import a plain `.tar` archive

```bash
yarn strapi import -f /path/to/my/file/backup.tar
```

```bash
npm run strapi import -- -f /path/to/my/file/backup.tar
```

## 提供一个加密密钥 {#provide-an-encryption-key}

🌐 Provide an encryption key

如果你正在从加密文件导入数据，可以使用 `-k` 或 `--key` 选项通过 `strapi import` 命令传递加密密钥。

🌐 If you are importing data from an encrypted file the encryption key can be passed with the `strapi import` command by using the `-k` or `--key` option.

### 示例：使用 `strapi import` 命令传递加密密钥 {#example-pass-the-encryption-key-with-the-strapi-import-command}

🌐 Example: Pass the encryption key with the `strapi import` command

```bash
yarn strapi import -f /path/to/my/file/export_20221213105643.tar.gz.enc --key my-encryption-key
```

```bash
npm run strapi import -- -f /path/to/my/file/export_20221213105643.tar.gz.enc --key my-encryption-key
```

## 绕过所有命令行提示 {#bypass-all-command-line-prompts}

🌐 Bypass all command line prompts

使用 `strapi import` 命令时，你需要确认导入将删除现有的数据库内容。`--force` 标志允许你跳过此提示。此选项对于以编程方式实现 `strapi import` 非常有用。对于编程使用，你还必须为加密文件传递 `--key` 选项。

🌐 When using the `strapi import` command, you are required to confirm that the import will delete the existing database contents. The `--force` flag allows you to bypass this prompt. This option is useful for implementing `strapi import` programmatically. For programmatic use, you must also pass the `--key` option for encrypted files.

### `--force` 选项的示例 {#example-of-the---force-option}

🌐 Example of the `--force` option

```bash
yarn strapi import -f /path/to/my/file/export_20221213105643.tar.gz.enc --force --key my-encryption-key
```

```bash
npm run strapi import -- -f /path/to/my/file/export_20221213105643.tar.gz.enc --force --key my-encryption-key
```

## 导入时排除数据类型 {#exclude-data-types-during-import}

🌐 Exclude data types during import

默认的 `strapi import` 命令会导入你的内容（实体和关系）、文件（资源）、项目配置和模式。`--exclude` 选项允许你通过传递以逗号分隔且类型之间无空格的字符串来排除内容、文件和项目配置。你不能排除模式，因为模式匹配用于 `strapi import`。

🌐 The default `strapi import` command imports your content (entities and relations), files (assets), project configuration, and schemas. The `--exclude` option allows you to exclude content, files, and the project configuration by passing these items in a comma-separated string with no spaces between the types. You can't exclude the schemas, as schema matching is used for `strapi import`.

:::warning

用 `--exclude` 或 `--only` 略过的阶段不会在你的目标实例中被清除：它们现有的数据会被保留。例如，如果你排除了 `config`，目标实例中已有的项目配置将保持不变。完全导入的阶段会完全替换目标实例中对应的数据。

🌐 Stages omitted with `--exclude` or `--only` are not wiped in your target instance: their existing data is preserved. For example, if you exclude `config`, the project configuration already present in your target instance is left untouched. Stages that are imported fully replace the corresponding data in the target instance.

:::

:::note

像图片这样的媒体由文件（资源）和数据库中的实体组成。如果使用 `--exclude` 标志来移除资源，数据库记录仍然会保留，并可能显示为断开的链接。

🌐 Media such as images consist of the file (asset) and the entity in the database. If you use the `--exclude` flag to remove assets, the database records are still included, and could render as broken links.

:::

### 示例：从导入中排除资源 {#example-exclude-assets-from-an-import}

🌐 Example: exclude assets from an import

```bash
yarn strapi import -f /path/to/my/file/export_20221213105643.tar.gz.enc --exclude files
```

```bash
npm strapi import -- -f /path/to/my/file/export_20221213105643.tar.gz.enc --exclude files
```

## 在导入时仅包含指定的数据类型 {#include-only-specified-data-types-during-import}

🌐 Include only specified data types during import

默认的 `strapi import` 命令会导入你的内容（实体和关系）、文件（资源）、项目配置和模式。`--only` 选项允许你仅通过传递一个不带空格的逗号分隔类型字符串来导出列出的项目。可用的值为 `content`、`files` 和 `config`。模式始终会被导入，因为模式匹配用于 `strapi import`。

🌐 The default `strapi import` command imports your content (entities and relations), files (assets), project configuration, and schemas. The `--only` option allows you to export only the listed items by passing a comma-separated string  with no spaces between the types. The available values are `content`, `files`, and `config`. Schemas are always imported, as schema matching is used for `strapi import`.

:::note

像图片这样的媒体包含文件（资源）和数据库中的实体。如果你使用 `--only` 标志导入 `content`，资源数据库记录仍然会被包含，并可能显示为断开的链接。

🌐 Media such as images consist of the file (asset) and the entity in the database. If you use the `--only` flag to import `content` the asset database records are still included, and could render as broken links.

:::

### 示例：仅导入项目配置 {#example-import-only-the-project-configuration}

🌐 Example: import only the project configuration

```bash
yarn strapi import -f /path/to/my/file/export_20221213105643.tar.gz.enc --only config
```

```bash
npm strapi import -- -f /path/to/my/file/export_20221213105643.tar.gz.enc --only config
```

## 导入时筛选内容类型 {#filter-content-types-during-import}

🌐 Filter content types during import

`--exclude-content-types` 和 `--only-content-types` 选项让你可以将导入限制到特定的内容类型。两个选项都接受用逗号分隔的内容类型 UID 列表（例如，`api::article.article`）。未知的 UID 会在启动时根据 Strapi 的模式进行验证。

🌐 The `--exclude-content-types` and `--only-content-types` options let you scope an import to specific content types. Both options accept a comma-separated list of content-type UIDs (for example, `api::article.article`). Unknown UIDs are validated against the Strapi schema at startup.

:::warning Warning: Restore behavior

- 当你使用 `--exclude-content-types` 时，被排除类型的数据会在目标地被**保留**——导入不会在恢复之前清除这些记录。
- 当你使用 `--only-content-types` 时，预导入清除只针对列出的 UID 生效，其他内容保持不变。

:::

### 排除特定内容类型的导入 {#exclude-specific-content-types-from-import}

🌐 Exclude specific content types from import

```bash
yarn strapi import -f export_20221213105643.tar.gz.enc --exclude-content-types api::article.article
```

```bash
npm run strapi import -- -f export_20221213105643.tar.gz.enc --exclude-content-types api::article.article
```

### 只导入特定内容类型 {#import-only-specific-content-types}

🌐 Import only specific content types

```bash
yarn strapi import -f export_20221213105643.tar.gz.enc --only-content-types api::article.article,api::category.category
```

```bash
npm run strapi import -- -f export_20221213105643.tar.gz.enc --only-content-types api::article.article,api::category.category
```