---
title: 准备您的 CSV 文件
description: 完整的分步指南，指导您将数据格式化以导入 Twenty。
---

## 概览

本指南将引导您准备 CSV 文件，以成功完成导入。 请按照以下步骤操作以避免错误。

## 步骤 1：检查文件要求

开始之前，请确保您的文件满足以下要求：

| 要求       | 详情                |
| -------- | ----------------- |
| **格式**   | CSV、XLSX 或 XLS    |
| **大小限制** | 每个文件最多 10,000 条记录 |
| **编码**   | 建议使用 UTF-8        |
| **结构**   | 每个文件仅一种对象类型       |

<Note>对于超过 10,000 条记录的数据集，请拆分为多个文件，或使用[API 导入](/l/zh/user-guide/data-migration/how-tos/import-data-via-api)。</Note>

## 步骤 2：下载示例文件

**这是最重要的一步。** 示例文件展示了 Twenty 期望的准确列名和格式。

1. 进入对象视图（人员、公司等）
2. 点击 **⋮** → **导入记录**
3. 点击 **下载示例文件**
4. 将此文件用作模板

<Note>**专业提示：** 改为导出少量现有记录。 这将为您提供数据应如何格式化的真实示例，并且在导入过程中列名会自动映射。</Note>

## 步骤 3：移除重复值

Twenty 会对某些字段强制唯一性。 重复项会导致导入错误。

| 对象        | 唯一字段               |
| --------- | ------------------ |
| **人员**    | `id`, `email`      |
| **公司**    | `id`, `domain`     |
| **自定义对象** | `id`，以及任何您标记为唯一的字段 |

**导入之前：**

1. 按唯一字段（email 或 domain）对电子表格排序
2. 删除或合并重复的行
3. 检查 Twenty 中是否已存在重复项

<Warning>**软删除的记录计入唯一性。** 位于“命令菜单 → 查看已删除的记录”中的记录会导致重复错误。 请永久删除这些记录，或将其恢复并更新。</Warning>

## 步骤 4：正确格式化各字段类型

不同的字段类型需要特定格式。 以下是完整参考：

### 文本字段

* 无需特殊格式
* 首尾空格将自动去除

### 电子邮件字段

* 必须是有效的电子邮件格式：`name@domain.com`
* 必须唯一（文件内及 Twenty 中不得重复）
* 对于附加电子邮件，请在 **Emails / Additional Emails** 列中使用此格式：

```
["jane@twenty.com","jane.doe@twenty.com"]
```

### 域名字段

* **推荐格式**：`https://domain.com`
* 这与邮箱/日历同步所使用的格式一致（可防止重复）
* 填写这两列：
  * **Domain / Domain Label**：`domain.com`
  * **Domain / Domain URL**：`https://domain.com`
* 在您的文件内以及在 Twenty 中必须唯一

### 电话字段

电话是一个**嵌套字段**，需要多列：

| 列                                       | 示例           |
| --------------------------------------- | ------------ |
| **Phones / Primary Phone Number**       | `4159095555` |
| **Phones / Primary Phone Country Code** | `US`         |
| **电话 / 主电话号码国际区号**                      | `+1`         |

### 地址字段

地址是一个**嵌套字段**，包含多个列（有些可以留空）：

* **Address / Address 1**：街道地址第 1 行
* **Address / Address 2**：街道地址第 2 行（可选）
* **Address / City**：城市名称
* **Address / State**：州或省
* **Address / Country**：国家名称
* **Address / Post Code**：邮政/ZIP 编码

### 日期字段

在整个文件中使用一致的格式：

* `YYYY-MM-DD`（推荐）：`2024-03-15`
* ISO 8601：`2024-03-15T10:30:00Z`

### 数字字段

* 仅数字（无文本）
* 小数使用点号：`1234.56`
* 不使用千位分隔符（不要写成 `1,234.56`）

### 货币字段

货币是一个**嵌套字段**，需要两列，且**两列都必须填写**：

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

### 布尔字段

使用大写：`TRUE` 或 `FALSE`

<Warning>小写的 `true` 或 `false` 将无法使用。</Warning>

### 选择字段

使用选项的**API 名称**，而不是显示标签。

**如何查找 API 名称：**

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

<Note>新的选择项不会自动创建。 请在导入前于 **设置 → 数据模型** 中添加它们。</Note>

### 多选字段

以数组格式使用 API 名称：

```
["VALUE1","VALUE2"]
```

### 数组字段

使用 JSON 数组格式：

```
["value1","value2"]
```

### 评分字段

使用以下格式：`RATING_1`、`RATING_2`、`RATING_3`、`RATING_4` 或 `RATING_5`

### 链接/URL 字段

填写两列：

* **Links / Link Label**：`Twenty`
* **Links / Link URL**：`https://twenty.com`

对于次要链接，请使用 **Links / Secondary Links** 列：

```
[{"url":"https://twenty.com","label":"Twenty"}]
```

### JSON 字段

使用有效的 JSON 格式：

```
{"key":"value","key2":"value2"}
```

### ID 字段

* **可选**：如未提供，Twenty 将自动生成 ID
* **格式**：UUID（例如：`c776ee49-f608-4a77-8cc8-6fe96ae1e43f`）
* **使用场景**：包含 ID 以更新现有记录，而不是创建新记录

## 步骤 5：添加关系列（如果要关联记录）

要将记录关联到其他对象（例如，将人员关联到公司），请添加包含关联记录唯一标识符的列。

**示例**：将人员关联到公司

在您的人员 CSV 中添加一列：

```
firstName,lastName,email,companyDomain
John,Smith,john@acme.com,https://acme.com
Jane,Doe,jane@widgets.co,https://widgets.co
```

**关系的重要规则：**

* 父记录必须已存在于 Twenty 中
* 使用**域名 URL** 格式（`https://domain.com`），而不是标签
* 仅映射一个唯一标识符（不要同时包含 `companyId` 和 `companyDomain`）
* 对于工作区成员，请使用其**电子邮箱**（而不是姓名）

<Warning>
**导入顺序很重要！**

先导入“1”端，再导入“多”端：
1. **公司** 优先
2. **人员** 其次（包含公司引用）
3. **机会** 第三

在引用之前，父记录必须已存在。
</Warning>

详细说明请参见[如何导入关系](/l/zh/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv)。

## 步骤 6：确保 Twenty 中存在这些字段

导入会创建**记录**，而非**字段**。 要导入的所有字段必须已在您的数据模型中存在。

**导入前：**

1. 进入 **设置 → 数据模型**
2. 选择您的对象
3. 创建所需的任何自定义字段
4. 记录准确的字段名称（必须与列标题匹配）

## 步骤 7：最终检查清单

在上传文件之前，请确认：

<Check>文件为 CSV、XLSX 或 XLS 格式</Check>
<Check>文件少于 10,000 条记录</Check>
<Check>编码为 UTF-8</Check>
<Check>没有重复的电子邮箱（针对人员）或域名（针对公司）</Check>
<Check>日期在全篇使用一致的格式</Check>
<Check>域名使用 `https://domain.com` 格式</Check>
<Check>布尔字段使用 `TRUE` 或 `FALSE`（大写）</Check>
<Check>选择字段使用 API 名称，而非显示标签</Check>
<Check>所有自定义字段已存在于 设置 → 数据模型 中</Check>
<Check>父记录先于子记录导入</Check>
<Check>关系列引用现有记录</Check>

## 常见错误及避免方法

| 错误                  | 解决方案                         |
| ------------------- | ---------------------------- |
| 使用 `true` 而非 `TRUE` | 布尔值必须为大写                     |
| 在选择字段中使用显示标签        | 在“设置”中查找并使用 API 名称           |
| 在公司之前导入人员           | 始终先导入父对象                     |
| 货币字段缺少货币代码          | 填写金额和货币两列                    |
| 域名格式错误              | 始终使用 `https://domain.com` 格式 |
| 为关系映射了多个唯一字段        | 仅映射一个（域名或 ID，不要同时映射）         |

## 下一步

您的文件已准备就绪！ 现在：

* [导入公司](/l/zh/user-guide/data-migration/how-tos/import-companies-via-csv)（先导入这些）
* [导入联系人](/l/zh/user-guide/data-migration/how-tos/import-contacts-via-csv)
* [修复任何导入错误](/l/zh/user-guide/data-migration/how-tos/fix-import-errors)