从旧工具迁移与素材库迁移

换工具这件事，难的从来不是“把文件复制过去”——那部分是机械的，难的是迁移之后你的工作方式能不能无缝接上。

这一篇讲两类迁移：换素材软件，以及换机器/换库。

第一类：从别的素材管理软件迁过来

不同工具的模型差异很大，迁之前必须先搞清三件事。

目标工具的模型是什么。 Eagle 的核心模型是：

关键认知：Eagle 允许一个素材属于多个文件夹吗？ 从 API 看，item.folders 是一个文件夹 ID 数组——所以在数据结构层面它是可以关联多个文件夹的。但实际使用中仍应遵循“一个稳定归属”的实践原则，因为过多归属会让浏览体验变得混乱。

旧工具的概念要往哪儿映射。 一张对照表：

注意最后一行：智能相册类的东西没法“搬”，只能”重建“。 迁移时先把动态查询记下来，导入完成后再在 Eagle 里用智能文件夹重建。

一个务实的迁移顺序

第 1 步：先导出一份清单。

在旧工具里，把所有收藏夹名称、每个收藏夹的数量、标签列表、评分分布导出来（截图或表格都行）。

这份清单的作用是验收依据。没有它，你无法判断导入是否完整。

第 2 步：结构映射。

对照上面的表，把旧工具的收藏夹映射成 Eagle 的文件夹，关键词映射成标签。

这一步的关键是简化。 很多人在这一步失败，是因为试图把旧工具的层级原样搬过去——而那个层级当初可能就不是为了检索设计的。

判断标准很简单：如果你的文件夹超过三层，停下来重新想。

第 3 步：小批量试导。

先导一个收藏夹进去，检查：

• 文件数量对不对
• 缩略图正常吗
• 标签带过来了吗
• 名称和格式信息有没有丢

旧工具的元数据映射不上是常态。 比如某些工具的“星级”和”收藏“是两个维度，映射到 Eagle 的单一评分上会丢失信息——这时候要有取舍的判断，而不是硬塞。

第 4 步：全量导入。

Eagle 支持多种添加方式：从文件夹添加、拖拽、浏览器扩展收集，以及 API 方式添加（本地路径、URL、base64、书签）。

批量自动化场景可以考虑用 API 或 Web API——Build 21 之后 Web API v2 与 Plugin API 能力对齐，覆盖条目管理、文件夹、标签、资源库七大类，还内置了 Playground 测试界面，不写代码也能试各个接口。

第 5 步：验收。

拿第 1 步的清单逐项对照：数量对不对？有没有空文件夹？标签有没有变成同义词的集合？

第 6 步：整理，不要立刻用。

刚迁进来的库，标签很可能一团糟。至少做一次标签清理再投入使用，否则你会用一个难用的库，过几天就放弃了。

常见坑：迁移完成后舍不得删旧工具的数据，于是半年后你有两个库同时在用，每个都不完整。旧工具的数据应该保留到新库通过验收之后，再决定是否清空。 提前清空就没有退路了。

第二类：迁移资源库本身（换机器、换盘）

这一类和“换工具”完全不同——素材不变，只是位置变了。

Eagle 的资源库是一个文件夹。 它可以被整体复制到另一台设备或磁盘。这是迁移的基础。

基本流程：

1. 确认新位置的磁盘空间足够。
2. 完全退出 Eagle。 这一步不能省——在 Eagle 运行时复制，可能复制到不完整的状态。
3. 复制整个库文件夹到新位置。
4. 在 Eagle 里指向新的库路径。
5. 打开后抽查若干素材，确认正常。

多个库的情况： 如果你维护多个资源库，每个都是独立的文件夹。要注意确认自己连的是哪个库——Eagle 的 API 提供了读取当前库信息的能力（库名称、库路径、最后修改时间），迁移后如果发现内容不对，先查是不是连错了库。

常见坑：在 Eagle 运行时做复制。看起来复制成功了，实际上某些文件可能处于写入状态，导致新库不完整。任何迁移动作前先退出应用。

迁移前的备份纪律

这一条适用于上面两类迁移。

官方的建议很清楚：定位库目录，把整个库文件夹复制到另一台设备或磁盘，并确认复制已经完成。

“整个库”这三个字要强调： 只复制部分图片，会让其余的库数据留在备份之外——而那些数据（标签、注释、文件夹结构）恰恰是不可再生的，因为它们是你几年积累的判断。

同步不等于备份。 这是个容易混淆的点：同步会把编辑和删除也传播到同步位置，所以它不能算作独立的可恢复副本。你需要的是一个和工作文件分开放的、真正独立的副本。

一个具体的例子说明为什么这些数据不可再生：

假设你三年里给 800 张素材写过注释，说明“这张海报的日期分段值得参考””这张的字体搭配适合小标题““这张构图在窄屏会崩”。这些文字在任何其他软件里都不存在。

素材文件丢了还能从别处再找（或者找不回来了，但至少不是系统性问题）；而这几万字注释一旦丢了，你损失的不是文件，是几年积累下来的判断。

这就是为什么“复制整个库”不是一个可以讨价还价的要求。

导入时的三个坑

坑一：元数据没跟着走。

从旧工具导出时，注意选择保留元数据的方式。某些工具导出成“纯图片 + 一个 CSV 清单”，这种情况下 CSV 里的标签和注释需要你另外想办法写回 Eagle，不能指望导入时自动关联。

这个坑的隐蔽之处在于：导入看起来是成功的。 图片都在，只是标签全没了，你可能过几周才发现。

应对：导入后立刻抽查 10 张，确认标签和注释是否带过来了。

坑二：文件名的非法字符。

不同系统对文件名的限制不同，跨系统迁移时可能遇到分隔符冲突。批量导入时如果某些文件静默失败，先怀疑这个。

应对：导入后核对数量，对不上就按格式分组检查。

坑三：导入时间戳全部变成“今天”。

这会影响排序和筛选——“最近一周新增的”这类条件会失效。

应对：如果你在意导入时间，注意这个字段可以被显式设置。API 层面提供了修改导入时间的能力（需要 Eagle 4.0 build18 或更高版本），适用于批量导入历史文件、迁移等需要保留原始时间戳的场景。

let item = await eagle.item.getById('item_id');
item.importedAt = new Date('2024-01-01').getTime();
await item.save();

注意：设置值必须为正整数时间戳，无效值会被忽略。

迁移后的三个专项检查

检查一：链接依赖。

如果你在库里保存了 InDesign 之类的生产文件，它们可能链接到别处存放的图形资源。清理或重组生产材料之前先检查链接关系，否则文档会找不到它的链接对象。

这类文件最好留在原来的项目目录里，不要塞进素材库。

检查二：路径相关的失效。

从旧工具迁移过来的素材，可能有指向旧位置的路径记录。这些记录在新环境里是无效的。逐个清理，或者干脆知道它们在那儿，避免以后被误用。

检查三：重复素材。

两个库合并最容易产生重复——同一张图在两边都存在。这会在你之后整理时突然冒出来。迁移时主动做一次去重，比事后被几千条重复项淹没要好。

一个更根本的建议

如果你的旧工具用得还不算痛苦，不要急着迁。

迁移的真实成本不在导入那一步，而在迁完之后重新建立检索习惯的那个阶段。那个阶段可能是几周的“到处都搜不到”的挫败期。

判断要不要迁，可以问三个问题：

1. 旧工具里有没有你现在找不到的东西？
2. 它的能力上有没有你确实需要、但一直得不到的功能？
3. 你的素材量级是不是已经大到旧工具明显吃力了？

三个都是“否”，那就不迁。 折腾一个新库的成本，比你从旧工具里省下的那点麻烦要高得多。

一个可执行的迁移检查清单

迁移前： - [ ] 导出旧库清单（文件夹、数量、标签、评分分布） - [ ] 完整备份旧库和目标库 - [ ] 记录哪些概念需要“重建”而非”搬运“ - [ ] 确认目标位置的空间

迁移中： - [ ] 退出应用再复制 - [ ] 小批量先导一个文件夹验证 - [ ] 全量导入 - [ ] 用清单逐项验收数量

迁移后： - [ ] 做一次标签清理 - [ ] 检查重复素材 - [ ] 检查路径失效记录 - [ ] 保留旧库直到新库用满一个月 - [ ] 把旧库做一份离线归档，而不是直接删除

最后一条是关键：旧库的最终归宿是“归档”，不是”删除“。 归档一份压缩包占不了多少空间，但给了你永久的退路。

常见坑：迁移时只搬文件夹结构，不搬标签和注释。文件夹结构是肉眼可见的，标签和注释不是——结果是新库里东西都在，但一样都找不到。 迁之前先确认标签和注释有导出方案。

整理人：WorkBuddy