Huly Notion 导入指南使用 import-tool 将 Notion 导出数据完整迁移至 Huly【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform本文是 Huly 平台中Notion → Huly 数据迁移的实战指南。内容基于仓库内官方文档 dev/import-tool/docs/notion/README.md并结合 import-tool 入口源码 与 Notion 导入器实现 进行源码级讲解。读完本文你将掌握如何从 Notion 正确导出内容、如何通过 Docker 一键把导出数据导入 Huly 工作区、两种导入模式的差异与适用场景、以及导入器在底层如何处理层级、内部链接、图片与附件。一、前置准备从 Notion 正确导出内容迁移的第一步是在 Notion 侧完成数据导出。请严格按以下步骤操作打开 Notion 官方导出入口按官方指南导出你的全部内容官方操作路径为 Notion 设置中的 Export your content导出格式务必选择Markdown CSV。这是整个迁移的前提——Huly 的 Notion 导入器只支持解析该格式产生的目录结构与文件解压导出的归档文件到一个本地目录下文统称为导出目录例如/path/to/export。导出完成后你会得到一个目录其中包含大量以 Notion 页面命名的.md文件文件名带 32 位字符的 Notion ID形如页面名称 abcdef0123...32 位.md若干.csv文件对应 Notion Database 导出图片、PDF、文档等附件文件顶层目录即为 Notion 中的顶层页面对应 Huly 的 Teamspace。注意Notion 导出的index.html位于导出根目录会被导入器显式忽略因为它只是 Notion 的预览页不承载有效数据。二、认识 Huly Import ToolHuly 仓库提供了独立的导入工具包 dev/import-tool它被打包为 Docker 镜像hardcoreeng/import-tool:latest对应 Dockerfile镜像内入口为打包后的bundle.js。该工具当前支持三类导入导入方式命令说明Notion 直接导入import-notion-with-teamspaces/import-notion-to-teamspace本文主题见 官方指南ClickUp 任务导入import-clickup-tasks从 CSV 导入任务见 ClickUp 指南统一格式导入import推荐的通用迁移方案见 Unified Import Format 指南工具的总体说明见 dev/import-tool/README.md。官方建议对于简单迁移可直接使用 Notion/ClickUp 直接导入对于复杂场景或不在支持列表中的系统优先采用统一格式Unified Format。必需的环境变量FRONT_URL运行导入前必须设置FRONT_URL环境变量指向你的 Huly 前端地址。从源码看getFrontUrl() 在未提供该变量时会直接报错退出const frontUrl process.env.FRONT_URL if (frontUrl undefined) { console.error(please provide front url) process.exit(1) } return frontUrl这是因为导入器需要先从{FRONT_URL}/config.json拉取服务配置尤其是ACCOUNTS_URL账号服务地址才能完成登录与工作区连接。自托管部署时请将其改为你自己的前端地址。三、运行导入两种模式将上一步解压好的导出目录挂载到容器的/data然后从以下两种模式中选择其一。模式一保留原始 Teamspace 结构docker run \ -e FRONT_URLhttps://huly.app \ -v /path/to/export:/data \ hardcoreeng/import-tool:latest \ -- bundle.js import-notion-with-teamspaces /data \ --user your.emailcompany.com \ --password yourpassword \ --workspace workspace-id该模式会扫描导出目录将 Notion 中的顶层页面自动重建为 Huly 的 Teamspace对应源码中的createTeamspaces()见 notion.ts页面层级关系保持原样。模式二导入到单个 Teamspacedocker run \ -e FRONT_URLhttps://huly.app \ -v /path/to/export:/data \ hardcoreeng/import-tool:latest \ -- bundle.js import-notion-to-teamspace /data \ --user your.emailcompany.com \ --password yourpassword \ --workspace workspace-id \ --teamspace teamspace-name-to-be-created该模式会把全部内容合并进一个新建的 Teamspace中适合迁移后需要统一收拢、不保留原始空间划分的场景。相比模式一额外多一个--teamspace参数用于指定新建 Teamspace 的名称源码见 index.ts。命令行参数详解参数简写必填含义dir—是挂载到容器内的导出目录路径示例中为/data--user-u是登录 Huly 的邮箱账号--password-p是账号密码--workspace-w是目标工作区的 URLworkspace url即在浏览器地址栏中显示的 workspace 标识--teamspace-t仅模式二新建 Teamspace 的名称注意--user、--password、--workspace三个参数在 CLI 定义中均为.requiredOption必填缺一不可且authorize()中三者任一为空都会跳过导入流程见 index.ts。四、底层实现解析导入器是如何工作的理解底层实现有助于你判断导出目录是否需要预处理以及排查导入失败的根因。以下分析均基于 packages/importer/src/notion/notion.ts。4.1 授权与连接流程无论哪种模式导入都会先经过 authorize()请求{FRONT_URL}/config.json获取ACCOUNTS_URL通过账号客户端用邮箱/密码登录拿到token与socialId用token拉取当前用户的工作区列表按workspace参数匹配目标工作区选中工作区后建立 Transactor 连接createClient并以TxOperations封装事务操作同时构造FrontFileUploader用于把图片与附件上传到 Huly 前端服务。也就是说执行导入的账号必须拥有目标工作区的访问权限且目标工作区必须真实存在workspace 匹配失败会打印Workspace not found并静默返回。4.2 文件扫描与元数据收集导入器会递归读取导出目录readdir(dir, { recursive: true })过滤掉目录项与根目录的index.html然后为每个文件构建两类元数据FileMetadata是否为文件夹、所在层级level、扩展名、是否含子项DocumentMetadataHuly 内部生成的文档 ID、原始名称、Notion ID、父级 Notion ID、子根SubRootID、MIME 类型与文件大小。其中关键的Notion ID 提取逻辑extractNotionId()是从文件名中匹配32 位 [\w\d] 字符数据库导出会带_all后缀const matched decoded.match(/ ([\w\d]{32}(_all)?)(\.|$)/)这也是为什么文档标题中如果混入过长无空格字符串可能干扰识别——文件名格式应尽量保持 Notion 默认导出样式。4.3 文件类型分类与处理根据元数据getDataProcessor() 将每个文件分流文件特征处理方式说明.md文件importPageDocument作为页面文档导入内容由 Markdown 转换.csv且含子项createDBPageWithAttachments创建一个页面占位文档并把 CSV 作为附件挂到该页面下.csv且名字匹配*_allimportDBAttachment把数据库的全量导出 CSV 作为附件挂到对应数据库页面非文件夹、有扩展名、存在父级importAttachment作为附件上传并挂载到父文档其他skip打印警告后跳过需要说明的是Notion Database 本身含视图、属性、行数据不会被导入为结构化数据库其 CSV 只能以附件形式保留原始数据——这与官方文档“Notion databases are not imported (CSV format not supported)”的限制一致。4.4 页面内容转换与链接重写页面导入的核心在 importPageDocument()读取.md文本经markdownToMarkup转换为 Huly 的内部富文本 JSON调用 preProcessMarkdown() 遍历节点树重写三类引用内部链接href 含 Notion ID→ 转换为 Huly 的reference节点指向目标页面的新 ID实现“文档间内部链接保持有效”图片→ 通过fileUploader.uploadFile上传后把src替换为上传后的文件 URL附件链接→ 转换为 Huly 的file节点并携带文件名、大小、MIME 信息通过uploadCollaborativeDoc将内容写入 Huly 协作文档存储计算排序rank后createDoc创建document:class:Document并通过parent字段挂到父文档下。链接类型判定getLinkType()逻辑为可被URL.canParse解析的视为外部链接跳过含 Notion ID 的视为内部链接其余有文件名的视为附件无法识别的标记为 UNKNOWN 并跳过。一个值得注意的边界当内部链接指向的页面不在本次导出范围内时导入器会打印Linked page not found (outside of this import)并保留原样不会导致导入失败。4.5 Teamspace 的创建细节模式一下导入器把导出目录中level 1的文件夹视为原始 Teamspace逐个调用createTeamspace创建。从 createTeamspace() 可见新建空间使用DefaultTeamspaceType描述固定为Imported from Notionprivate: false且不自动加入成员autoJoin: false。导入完成后可在 Huly 中按需调整空间可见性与成员。五、已知限制与注意事项依据官方文档与源码行为迁移前请知悉以下限制Notion 数据库不导入数据库的 CSV 导出不被解析为结构化数据不支持 CSV 格式仅作为附件保留在对应页面下评论不导入Notion 导出不包含评论内容因此评论无法迁移图片与文件必须在导出中包含若导出时未勾选包含文件则页面中的图片、附件将缺失对应节点无法重写为有效引用图片节点若无元数据匹配会被保留或失效根目录index.html会被忽略无父级信息即无 Notion ID 可提取的文件会被归类为普通附件或跳过无法正确建立层级模式一中若导出目录下没有任何一级文件夹spaceIdMap.size 0导入器会打印No teamspaces found in directory并终止见 notion.ts。六、导入完成后的预期效果导入完成后你可以在目标工作区中看到全部文档保留原始层级Notion 的父子页面关系在 Huly 中通过文档parent字段完整还原内部链接保持有效页面间互相引用会转换为 Huly 文档引用reference点击即可跳转图片与附件自动导入只要导出归档中包含了它们上传与挂载均在导入过程中自动完成数据库以页面 CSV 附件形式保留原始数据不丢失便于后续人工整理。建议在正式迁移前先用一个小的测试导出目录、配合测试账号走一遍两种模式确认导出格式与目录结构符合预期再对全量数据执行导入。七、参考与延伸阅读dev/import-tool/README.md导入工具总览与推荐导入方式说明dev/import-tool/docs/huly/README.md统一格式Unified Format导入完整指南含 YAML 空间配置与 Markdown 文档 frontmatter 规范dev/import-tool/docs/huly/example-workspace可直接套用的示例工作区包含 Teamspace、文档、任务、受控文档QMS的完整结构dev/import-tool/docs/clickup/README.mdClickUp CSV 任务导入指南dev/import-tool/src/index.tsCLI 命令注册、授权流程与参数定义packages/importer/src/notion/notion.tsNotion 导入器核心实现扫描、分类、Markdown 预处理、空间创建。如果你的数据来自 Notion 之外的系统或迁移复杂度较高需要任务、受控文档等结构官方推荐先转换为 统一导入格式以获得更完整、更可控的迁移能力。【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考