> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 修复导入错误

> 解决 CSV 导入错误的完整故障排除指南。

## 概览

导入无法正常工作？ 本指南将逐步帮助你识别并修复常见的导入错误。

## 导入验证的工作原理

上传文件并完成列映射后，Twenty 会对你的数据进行验证：

1. **开始验证** — Twenty 会逐行检查是否存在错误
2. **错误会被高亮** — 有问题的行将以**黄色**显示
3. **可就地修复** — 可在导入界面中直接编辑单元格
4. **或移除行** — 完全跳过有问题的记录

<Note>**在界面中修复错误。** 无需返回电子表格。 在导入过程中直接编辑单元格以节省时间。</Note>

## 分步故障排查

### 步骤 1：确定错误类型

点击高亮的行查看具体的错误信息。 常见错误类型：

| 错误消息                                                         | 含义                           |
| ------------------------------------------------------------ | ---------------------------- |
| 重复值以黄色高亮显示                                                   | 该值已存在于 Twenty 中，或在你的文件中出现了两次 |
| `{field} is not a valid {type}`（将鼠标悬停在黄色单元格上）                | 数据与预期格式不匹配                   |
| 必填字段被高亮显示                                                    | 必填字段为空                       |
| `Can't connect to {object}. No unique record found...`（导入失败） | 被引用的记录不存在                    |
| `Too many records. Up to 10000 allowed`（已阻止上传）               | 文件包含超过 10,000 条记录            |

### 步骤 2：修复错误

根据下面针对每种错误类型的具体说明进行处理。

***

## 错误：重复值

### 您将会看到什么

在开始导入之前，导入界面中包含重复值的行会被**黄色高亮**。

### 含义

唯一字段（电子邮件、域名）可能：

* 已存在于 Twenty 中
* 在你的文件中出现了两次

### 修复方法

**选项 1：编辑重复值**

1. 点击包含错误的单元格
2. 更改为唯一值
3. 继续导入

**选项 2：移除重复行**

1. 点击该行旁的 X
2. 导入时将跳过该行

**选项 3：让 Twenty 更新现有记录**

1. 确保你的文件包含唯一标识符（`email`、`domain` 或 `id`）
2. 映射该唯一标识符字段
3. Twenty 将更新现有记录，而不是创建重复项

<Note>
  **你也可以更新唯一字段。**

  * 如果保留 `id` 但更改 `email` → 将更新该电子邮件
  * 如果保留 `email` 但更改 `id` → 将更新该 id

  只要至少有一个唯一标识符匹配，Twenty 就会更新该记录。
</Note>

### 如何避免此错误

导入前：

1. 按唯一字段对电子表格进行排序
2. 删除重复行
3. 检查 Twenty 中是否已存在这些记录

<Warning>
  **软删除的记录也会计入唯一性。**

  检查 Command Menu → 查看已删除的记录。 其中的记录仍会参与唯一性校验。 将其永久删除，或还原后再更新。
</Warning>

了解更多详情：[唯一性约束](/l/zh/user-guide/data-migration/capabilities/uniqueness-constraints)

***

## 错误：格式无效

### 您将会看到什么

该单元格的值会以黄色高亮显示。 将鼠标悬停其上以查看错误信息：

```
{field name} is not a valid {field type}
```

### 含义

该数据与该字段类型的预期格式不匹配。

### 修复方法 — 按字段类型

#### 电子邮件

**问题：** 电子邮件格式无效
**解决方案：** 使用 `name@domain.com` 格式

```
❌ john.smith@
❌ john smith@acme.com
✓ john.smith@acme.com
```

#### 域

**问题：** 格式不一致可能导致重复
**解决方案：** 使用 `https://domain.com` 格式（推荐）

```
⚠️ acme.com         (valid, but not recommended)
⚠️ www.acme.com     (valid, but not recommended)
✅ https://acme.com  (recommended)
```

<Note>所有格式都有效，但推荐使用 `https://domain.com`，因为它与电子邮件/日历同步所用的格式一致。 使用其他格式可能会创建重复的公司。</Note>

#### 日期

**问题：** 无法识别的日期格式
**解决方案：** 在整个文件中一致使用 `YYYY-MM-DD` 格式

```
✓ 2024-03-15        (YYYY-MM-DD)
❌ 03/15/2024        (MM/DD/YYYY)
❌ 15/03/2024        (DD/MM/YYYY)
```

#### 电话

**问题：** 缺少必需的列
**解决方案：** 包含所有电话相关列

| 列                                       | 示例           |
| --------------------------------------- | ------------ |
| **Phones / Primary Phone Number**       | `4159095555` |
| **Phones / Primary Phone Country Code** | `US`         |
| **Phones / Primary Phone Calling Code** | `+1`         |

#### 布尔值

**问题：** 布尔值不正确
**解决方案：** 使用大写的 `TRUE` 或 `FALSE`

```
❌ true
❌ yes
❌ 1
✓ TRUE
✓ FALSE
```

#### 选择/多选

**问题：** 值与现有选项不匹配
**解决方案：** 使用**API 名称**，而非显示标签

如何查找 API 名称：

1. 进入 **设置 → 数据模型**
2. 选择对象和字段
3. 启用 **高级模式**（右下角切换）
4. 使用 API 名称（例如：`OPTION_1`，而不是 "Option 1"）

```
❌ High Priority
✓ HIGH_PRIORITY
```

#### 货币

**问题：** 缺少金额或货币代码
**解决方案：** 同时填写这两列

| 列                     | 示例        |
| --------------------- | --------- |
| **Amount / Amount**   | `1234.56` |
| **Amount / Currency** | `USD`     |

#### 数字

**问题：** 含非数字字符
**解决方案：** 只能使用数字，小数点用英文句点

```
❌ $1,234.56
❌ 1,234.56
✓ 1234.56
```

完整格式参考：[字段映射](/l/zh/user-guide/data-migration/capabilities/field-mapping)

***

## 错误：缺少必填字段

### 您将会看到什么

该行将以黄色高亮，并标出缺失的必填字段单元格。

### 含义

此行存在必填字段为空。

### 修复方法

**选项 1：输入一个值**

1. 点击空白单元格
2. 输入值
3. 继续导入

**选项 2：移除该行**

1. 如果没有该数据，点击 X 跳过该行

### 如何避免此错误

在导入之前，确定必填字段：

1. 进入 **设置 → 数据模型**
2. 选择你的对象
3. 检查哪些字段被标记为必填

***

## 错误：未找到关系

### 您将会看到什么

该错误会在**导入开始之后**出现 — 导入将因如下消息而失败：

```
Can't connect to company. No unique record found with condition: id = 7776ee49-f608-4a77-8cc8-6fe96ae1e43f
```

这意味着 Twenty 中没有具有该特定标识符的公司。

<Note>与其他错误不同，此错误不会在数据审核步骤中被捕获。 导入会开始执行，但在遇到缺失的关联时失败。</Note>

### 含义

你正在尝试关联一条在 Twenty 中不存在的记录。

### 修复方法

**选项 1：先导入父级记录**

1. 取消当前导入
2. 导入父级记录（例如，公司）
3. 然后导入子级记录（例如，人员）

**选项 2：修正引用值**

1. 检查文件中的引用值
2. 确保其与现有记录完全匹配
3. 核对格式：域名应为 `https://domain.com`

**选项 3：移除该关联**

1. 清空该单元格，以不带关联地进行导入
2. 稍后手动添加该关联

### 如何避免此错误

1. **按正确顺序导入：**
   * 先导入公司
   * 其次导入人员（包含公司引用）
   * 第三导入机会

2. **核对引用值：**
   * 导出父级记录以获取精确的标识符
   * 使用域名格式 `https://domain.com`
   * 检查拼写错误和大小写是否一致

<Warning>
  **若引用了不存在的记录，导入将失败。**

  始终先导入父对象，再导入子对象。
</Warning>

了解更多详情：[导入关系](/l/zh/user-guide/data-migration/capabilities/import-relations)

***

## 错误：文件过大

### 您将会看到什么

在上传文件时会出现该错误 — 上传将被完全阻止：

```
Too many records. Up to 10000 allowed
```

在减小文件大小之前，你将无法进入数据审核步骤。

### 含义

你的文件包含超过 10,000 条记录。

### 修复方法

**选项 1：拆分为多个文件**

1. 将数据分成每个不超过 10,000 条记录的文件
2. 分别导入每个文件
3. 保持导入顺序（先公司，后人员）

**选项 2：使用 API 导入**
对于非常大的数据集，请使用没有记录数量限制的 API。
参见：[如何通过 API 导入数据](/l/zh/user-guide/data-migration/how-tos/import-data-via-api)

***

## 错误：无法识别字段

### 含义

文件中的某一列无法映射，因为 Twenty 中不存在该字段。

### 修复方法

1. 进入 **设置 → 数据模型**
2. 选择你要导入的对象
3. 点击 **+ 添加字段**
4. 创建具有适当类型的自定义字段
5. 重新上传你的文件

<Note>CSV 导入会创建记录，而不是字段。 在导入之前，所有字段都必须已存在。</Note>

***

## 错误：用户关联为空

### 含义

你正在尝试将记录分配给某个用户（所有者、被指派者），但该关联未被映射。

### 常见原因

1. **用户尚未接受邀请** — 该用户在 Twenty 中尚不存在
2. **使用旧系统的用户 ID** — Twenty 无法匹配来自其他系统的 ID
3. **电子邮件格式错误** — 该邮箱与用户的 Twenty 账户不匹配

### 修复方法

1. 确保所有用户都已接受邀请加入你的 Twenty 工作区
2. 使用用户的电子邮箱地址（而不是姓名或旧系统的 ID）
3. 使用他们用于加入 Twenty 的同一邮箱

<Warning>
  **在导入之前，用户必须先接受邀请。**

  如果某个用户尚未接受邀请，引用该用户的记录将出现空的用户关联。
</Warning>

***

## 导入前清单

导入前检查以下项目以避免错误：

### 文件要求

<Check>文件为 CSV、XLSX 或 XLS 格式</Check>
<Check>文件少于 10,000 条记录</Check>
<Check>文件使用 UTF-8 编码</Check>

### 数据质量

<Check>无重复电子邮件（针对联系人）</Check>
<Check>无重复域名（针对公司）</Check>
<Check>所有日期采用一致的格式</Check>
<Check>所有域名使用 `https://domain.com` 格式</Check>

### 字段格式

<Check>布尔字段使用 `TRUE` 或 `FALSE`（大写）</Check>
<Check>选择字段使用 API 名称，而非显示标签</Check>
<Check>电话字段包含所有必需的列</Check>
<Check>货币字段同时包含金额和货币代码</Check>

### 关系

<Check>先导入父级记录，再导入子级记录</Check>
<Check>关联列引用现有记录</Check>
<Check>域名格式与 Twenty 的格式完全一致</Check>

### 数据模型

<Check>设置 → 数据模型 中已存在所有自定义字段</Check>
<Check>在导入前先创建所有选择项</Check>

***

## 仍有问题？

如果你已尝试以上解决方案：

1. **下载示例文件** — 了解 Twenty 期望的确切格式
2. **导出现有记录** — 将你的文件与可用数据进行对比
3. **用小批量测试** — 先尝试 5-10 行
4. **查看参考文章：**
   * [字段映射](/l/zh/user-guide/data-migration/capabilities/field-mapping)
   * [唯一性约束](/l/zh/user-guide/data-migration/capabilities/uniqueness-constraints)
   * [导入关系](/l/zh/user-guide/data-migration/capabilities/import-relations)
   * [错误处理](/l/zh/user-guide/data-migration/capabilities/error-handling)