跳转到主要内容

​
概览

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

​
导入验证的工作原理

上传文件并完成列映射后，Twenty 会对你的数据进行验证：
  1. 开始验证 — Twenty 会逐行检查是否存在错误
  2. 错误会被高亮 — 有问题的行将以黄色显示
  3. 可就地修复 — 可在导入界面中直接编辑单元格
  4. 或移除行 — 完全跳过有问题的记录
在界面中修复错误。 无需返回电子表格。 在导入过程中直接编辑单元格以节省时间。

​
分步故障排查

​
步骤 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 将更新现有记录，而不是创建重复项
你也可以更新唯一字段。
  • 如果保留 id 但更改 email → 将更新该电子邮件
  • 如果保留 email 但更改 id → 将更新该 id
只要至少有一个唯一标识符匹配，Twenty 就会更新该记录。

​
如何避免此错误

导入前：
  1. 按唯一字段对电子表格进行排序
  2. 删除重复行
  3. 检查 Twenty 中是否已存在这些记录
软删除的记录也会计入唯一性。检查 Command Menu → 查看已删除的记录。 其中的记录仍会参与唯一性校验。 将其永久删除，或还原后再更新。
了解更多详情：唯一性约束

​
错误：格式无效

​
您将会看到什么

该单元格的值会以黄色高亮显示。 将鼠标悬停其上以查看错误信息： 
{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)
所有格式都有效，但推荐使用 https://domain.com，因为它与电子邮件/日历同步所用的格式一致。 使用其他格式可能会创建重复的公司。

​
日期

问题： 无法识别的日期格式 解决方案： 在整个文件中使用一致的格式 
✓ 2024-03-15        (YYYY-MM-DD - recommended)
✓ 03/15/2024        (MM/DD/YYYY)
✓ 15/03/2024        (DD/MM/YYYY)

​
电话

问题： 缺少必需的列 解决方案： 包含所有电话相关列
列示例
Phones / Primary Phone Number4159095555
Phones / Primary Phone Country CodeUS
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 / Amount1234.56
Amount / CurrencyUSD

​
数字

问题： 含非数字字符 解决方案： 只能使用数字，小数点用英文句点 
❌ $1,234.56
❌ 1,234.56
✓ 1234.56
完整格式参考：字段映射

​
错误：缺少必填字段

​
您将会看到什么

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

​
含义

此行存在必填字段为空。

​
修复方法

选项 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 中没有具有该特定标识符的公司。
与其他错误不同，此错误不会在数据审核步骤中被捕获。 导入会开始执行，但在遇到缺失的关联时失败。

​
含义

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

​
修复方法

选项 1：先导入父级记录
  1. 取消当前导入
  2. 导入父级记录（例如，公司）
  3. 然后导入子级记录（例如，人员）
选项 2：修正引用值
  1. 检查文件中的引用值
  2. 确保其与现有记录完全匹配
  3. 核对格式：域名应为 https://domain.com
选项 3：移除该关联
  1. 清空该单元格，以不带关联地进行导入
  2. 稍后手动添加该关联

​
如何避免此错误

  1. 按正确顺序导入：
    • 先导入公司
    • 其次导入人员（包含公司引用）
    • 第三导入机会
  2. 核对引用值：
    • 导出父级记录以获取精确的标识符
    • 使用域名格式 https://domain.com
    • 检查拼写错误和大小写是否一致
若引用了不存在的记录，导入将失败。始终先导入父对象，再导入子对象。
了解更多详情：导入关系

​
错误：文件过大

​
您将会看到什么

在上传文件时会出现该错误 — 上传将被完全阻止： 
Too many records. Up to 10000 allowed
在减小文件大小之前，你将无法进入数据审核步骤。

​
含义

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

​
修复方法

选项 1：拆分为多个文件
  1. 将数据分成每个不超过 10,000 条记录的文件
  2. 分别导入每个文件
  3. 保持导入顺序（先公司，后人员）
选项 2：使用 API 导入 对于非常大的数据集，请使用没有记录数量限制的 API。 参见：如何通过 API 导入数据

​
错误：无法识别字段

​
含义

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

​
修复方法

  1. 进入 设置 → 数据模型
  2. 选择你要导入的对象
  3. 点击 + 添加字段
  4. 创建具有适当类型的自定义字段
  5. 重新上传你的文件
CSV 导入会创建记录，而不是字段。 在导入之前，所有字段都必须已存在。

​
错误：用户关联为空

​
含义

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

​
常见原因

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

​
修复方法

  1. 确保所有用户都已接受邀请加入你的 Twenty 工作区
  2. 使用用户的电子邮箱地址（而不是姓名或旧系统的 ID）
  3. 使用他们用于加入 Twenty 的同一邮箱
在导入之前，用户必须先接受邀请。如果某个用户尚未接受邀请，引用该用户的记录将出现空的用户关联。

​
导入前清单

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

​
文件要求

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

​
数据质量

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

​
字段格式

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

​
关系

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

​
数据模型

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

​
仍有问题？

如果你已尝试以上解决方案：
  1. 下载示例文件 — 了解 Twenty 期望的确切格式
  2. 导出现有记录 — 将你的文件与可用数据进行对比
  3. 用小批量测试 — 先尝试 5-10 行
  4. 查看参考文章：