导入与导出
巴克励步
概述
知识库支持将外部结构化文件批量导入为文档树，也支持按篇或按库导出为 PDF、Word、Markdown、CSV、JSON 等格式，用于备份、迁移或对接下游系统。
操作步骤
步骤一：进入导入或导出入口
- 打开目标知识库空间。
- 在左侧 管理 分组中进入 导入记录 或 导出记录（部分界面写作「导入数据」「导出知识库」）。
- 单篇导出也可在文章详情页的 导出 菜单发起。
预期结果：看到历史任务列表及 导入数据 / 导出知识库（或 导出文章）按钮。
步骤二：从文件导入（六步向导）
适用于 CSV、JSON、Excel、Markdown 及 ZIP（Markdown） 等结构化来源。点击 导入数据 → 从文件导入，按向导逐步完成。
| 步骤 | 名称 | 说明 |
|---|---|---|
| 1 | 上传文件 | 选择本地文件；可先 下载模板 对照字段 |
| 2 | 解析文件 | 系统读取表头/结构，识别可映射列 |
| 3 | 配置字段 | 将文件列映射到平台字段（见下表） |
| 4 | 检查数据 | 预览解析结果，修正明显错误 |
| 5 | 选择导入位置 | 指定挂接到目录树的父节点 |
| 6 | 完成 | 提交任务；后台处理，可在导入记录查看进度 |
导入文件常用字段
| 字段 | 必填 | 说明 |
|---|---|---|
id |
否 | 行内唯一标识，仅用于导入时建立父子关系 |
parent_id |
否 | 父文档对应的 id 值 |
title |
是 | 文档标题 |
content_type |
是 | 正文类型，仅接受 html 或 markdown |
content |
否 | 文档正文 |
- 在步骤一阅读支持的格式说明，点击 点击这里下载模板 获取标准 CSV/表格样例。
- 按模板填写
title、content_type与content；多级目录时用id+parent_id表达层级。 - 点击 选择文件… 上传，逐步 下一步 直至提交。
- 任务创建后在 导入记录 查看成功/失败条数；失败行可下载日志后修正重导。
注意：
content_type 须与实际正文一致——Markdown 正文填 markdown，富文本 HTML 填 html。混用会导致 文档编辑器 渲染异常。大规模导入前建议在测试库跑通映射。预期结果：导入任务状态为成功；目录树出现对应层级的新文档。
步骤三：其他导入方式
除 从文件导入 外，导入页通常还提供：
| 方式 | 适用场景 |
|---|---|
| 导入 Baklib V1 文档 | 从 V1 整站迁移，需 V1 Token；步骤见 怎么将 V1 的内容导入到新版本？ |
| Markdown / ZIP | 本地已拆好的 .md 或多文件 ZIP 包 |
| Excel / CSV / JSON | 表格或 API 导出的结构化数据 |
各方式的字段映射界面略有差异，但核心字段（标题、正文类型、正文、层级）与上表一致。
预期结果：可选中目标导入类型并进入对应子向导。
步骤四：导出单篇文章
在 文档编辑器或阅读模式下，打开目标文档的 导出 功能。
- 选择导出格式（卡片单选）：
| 格式 | 说明 |
|---|---|
| 适合分享、打印 | |
| Word | 适合二次编辑、留档 |
| Markdown | 适合迁移；仅当前一篇为 .md，含子页面且多篇时打包为 ZIP |
| CSV | 结构化数据，列字段与 JSON 一致 |
| JSON | 与 CSV 行字段一致 |
- 选择 CSV 或 JSON 时，页面会展示字段说明表，便于与导入模板对照。
- 点击 开始导出。
- 在下方 导出记录 等待任务完成，点击下载链接保存文件。
预期结果：导出记录中出现新任务，完成后可下载对应格式文件。
步骤五：导出整库或子树
整库导出用于全量备份或迁出到其他系统。
- 进入知识库 导出记录（
/kb/{id}/exports）。 - 点击 导出知识库（或等价按钮）。
- 选择范围（整库 / 指定目录，以界面为准）与格式（常见为 CSV，正文为 HTML，资源链接保留原始绝对路径）。
- 任务完成后在列表下载。
提示：导出含图片、附件时文件体积较大；CSV/JSON 中的外链在离线环境可能失效，迁移前请评估是否需一并导出资源库文件或启用 V1 导入时的「转存资源」选项。
预期结果：离线包或 CSV 可在本地打开，目录层级与线上一致。
步骤六：导入导出后的校验
- 导入后：在目录树抽检 3～5 篇，确认标题层级、正文渲染、图片是否可访问。
- 导出后：随机打开导出文件，检查内链、代码块、表格是否完整。
- 若需对外发布，导入完成后按 发布到 Wiki 应用站点 同步到 Wiki 应用。
预期结果：内容与线上一致或符合迁移预期；问题可在 文档编辑器 中手工修正或调整映射后重导。
常见问题
Q：导入时
A：填同一文件中某行的
parent_id 填什么？A：填同一文件中某行的
id 值，表示该文档为其子页。顶级文档的 parent_id 留空；导入位置步骤也可指定统一父节点。Q：Markdown ZIP 包如何组织？
A：通常每个
A：通常每个
.md 对应一篇文档，压缩包内相对路径与附件引用需与平台解析规则一致；首次使用建议先用小样本 ZIP 试导。Q：单篇导出 Markdown 为什么是 ZIP？
A：当导出范围包含子页面或多篇文档时，系统会将多篇
A：当导出范围包含子页面或多篇文档时，系统会将多篇
.md 及关联资源打包为 ZIP；仅导出当前一篇且无子页时为单个 .md 文件。Q：CSV 导出与 JSON 导出有什么区别？
A：字段结构相同，仅序列化格式不同；选型取决于下游系统（表格工具偏好 CSV，程序处理偏好 JSON）。
A：字段结构相同，仅序列化格式不同；选型取决于下游系统（表格工具偏好 CSV，程序处理偏好 JSON）。
Q：本地 PDF 能否直接导入？
A：不支持 PDF 直导；需先转为结构化数据，见 本地 PDF 文档迁移到线上知识库。
A：不支持 PDF 直导；需先转为结构化数据，见 本地 PDF 文档迁移到线上知识库。
Q：导入失败常见原因？
A：必填字段缺失、
A：必填字段缺失、
content_type 非法、编码非 UTF-8、层级 id 循环引用等；查看任务详情中的失败行说明。相关阅读
- 文档目录树 — 目录树与导入导出入口
- 文档编辑器发文 — 单篇撰写与保存
- 文档编辑器功能参考 — 文档编辑器 语法与块级组件
- 知识库设置 — 回收站与操作日志
- 导入和导出的支持有哪些？ — 能力速查
- 怎么将 V1 的内容导入到新版本？ — V1 专用通道
- 本地 PDF 文档迁移到线上知识库 — 非结构化文档迁移