禅道批量导入需求需严格使用官方模板并规范操作：一、从产品→需求导出模板填写；二、在需求页导入并预览确认；三、超2000条可用cli命令行工具；四、异常时须修正编码、空行、特殊字符及优先级数值。

如果您在禅道中需要将大量已整理好的需求信息快速录入系统，但手动逐条添加效率低下，则可能是由于未使用标准模板或导入流程不规范导致失败。以下是完成禅道批量导入需求数据的具体操作步骤：

一、获取并填写标准需求导入模板

禅道仅支持基于其导出的模板文件进行需求导入，确保字段结构与系统数据库严格匹配，避免因列名、顺序或必填项缺失引发解析失败。

1、登录禅道系统，切换至“产品”视图。

2、点击左侧菜单栏中的“需求”，进入需求管理页面。

3、点击右上角“导出”按钮，选择“导出模板”，下载生成的 Template.xlsx 或 Template.csv 文件。

4、使用 Excel 或文本编辑器打开模板，按实际业务填写“标题”“模块”“优先级”“预计工时”“描述”等字段，注意不可删除或重命名任何表头列，且“标题”为必填项。

5、保存文件，确保扩展名仍为 .xlsx 或 .csv（若用记事本编辑 CSV，请另存为 UTF-8 编码格式）。

二、通过“导入”功能上传并确认数据

该方式直接调用禅道内置导入接口，适用于单次导入中小规模需求（建议单次不超过 500 条），系统会自动校验字段合法性并预览待入库记录。

1、返回需求管理页面，点击右上角“导入”按钮。

2、在弹出窗口中，点击“选择文件”，上传上一步保存的模板文件。

3、系统自动解析后，显示“导入预览”列表，请逐行核对标题、模块、优先级等关键字段是否正确映射。

4、确认无误后，点击“保存”，等待提示“导入成功 X 条需求”。

三、使用命令行工具执行离线批量导入（高级方式）

当需求数据量极大（如超 2000 条）、需定时自动化或规避浏览器上传限制时，可通过禅道后台提供的 CLI 工具绕过前端限制，直接写入数据库。

1、登录禅道部署服务器，进入禅道安装目录下的 bin 子目录。

2、执行命令：php ztcli.php import --type=requirement --file=/path/to/your/requirements.xlsx。

3、检查终端输出日志，若出现“Inserted X rows”即表示成功写入；若提示“Column 'xxx' not found”，说明模板字段与当前禅道版本不兼容。

4、刷新网页端需求列表，验证最新导入数据是否可见且状态正常。

四、处理常见导入异常的应急操作

导入失败常源于编码、空行、特殊字符或字段越界，需针对性修正原始文件后再重试，不可跳过校验强行提交。

1、若提示“文件格式错误”，请用 Excel 重新另存为 .xlsx 格式（非 .xls 或 .xlsm），并关闭所有公式与宏。

2、若提示“第 N 行标题为空”，请打开文件定位到对应行，删除整行空白数据，不可仅清空单元格内容。

3、若需求标题含中文引号、全角破折号或换行符，请统一替换为英文半角符号，并清除单元格内不可见控制字符（可用 TRIM + CLEAN 函数辅助清理）。

4、若提示“优先级超出范围”，请核对模板中“pri”列值是否仅为 1–4 的整数，禁止填写“高”“中”“低”等文字。