先把结论放前面：如果你的电脑里躺着几十上百个 EasyEDA Pro 工程，又有一半以上可能要被丢进 KiCad 继续维护，那 epro2kicad 这个命令行转换工具值得你花一个下午认真试试。它把 EasyEDA Pro 的 .epro 工程直接在终端里转成 KiCad 整套工程文件，全程不需要打开两次图形界面，不需要手动导出再导入，更不需要对着两个 EDA 的弹窗反复核对网络表。这篇文章是我用这个工具把一批历史项目从 EasyEDA Pro 迁到 KiCad 的实操记录，里面有安装方式、命令参数、转换原理和大量踩坑经验，适合准备做库迁移、格式交接、自动化构建的硬件工程师。

1. 为什么需要命令行转换工具

1.1 EasyEDA Pro 与 KiCad 的格式鸿沟

EasyEDA Pro（国内习惯叫立创 EDA 专业版）和 KiCad 虽然都是做 PCB 设计，但底层的文件格式完全是两套逻辑。EasyEDA Pro 的工程文件本质上是自有格式的 JSON 数据包，原理图和 PCB 的图形对象、网络连接、封装信息都塞在结构化的字段里，而 KiCad 用的是文本化的 s-expression 格式，从 .kicad_sch 到 .kicad_pcb 都是可以直接用编辑器打开的纯文本。这两者的差别有点像 Word 和 Markdown，一个是私有打包，一个是开放文本，互相读取本来就不容易。

更麻烦的是，EasyEDA Pro 的文件结构里还大量引用立创自己的元件库体系和封装库体系，很多封装在 KiCad 里根本没有对应名。就算人工导入，也会遇到"元器件找不到封装""焊盘形状对不上"这类问题。文件格式不兼容，加上第三方库依赖，导致两个工具之间不能靠简单的另存为完成转换。epro2kicad 做的事情，就是在命令行里把这一层转换逻辑封装好：解析 EasyEDA Pro 的工程数据，重新组织成 KiCad 的工程结构，并尽量把层、网络、封装、焊盘映射过去。

1.2 图形界面导入的痛点

其实 KiCad 官方和 EasyEDA Pro 本身都提供了一些交互式的导入办法，EasyEDA 有导出 KiCad 格式的入口，KiCad 也有导入其他 EDA 格式的插件。但是走图形界面的路，有几个实际痛点特别明显。

一是批量处理基本不可能。一次只能导一个工程，如果有 30 个历史工程要迁移，点 30 次鼠标只是入门，麻烦的是每个工程都可能弹提示、卡在封装缺失上，你必须在旁边盯着手工确认。二是可重复性差。同一个工程，这次导入和那次导入，选项稍微点错一点，结果就不一样。三是无法审计。图形界面转完就完事，日志不规范，出了问题你很难复盘是哪一步转错的。四是不好集成进自动化流程。硬件团队一旦上了 CI 或者版本化工程管理，就希望转换动作本身是一个可调用的命令，而不是人类坐在屏幕前点点点。

这些痛点，本质上都是"交互式操作"和"批量化、可脚本化"之间的冲突。只要你有超过一个工程要转，或者你希望转换步骤能写进自动化流水线，命令行工具的优势就压过图形界面了。

1.3 命令行的独特价值

epro2kicad 这类工具最大的价值在于把转换变成了一条可复用的指令。输入是 .epro 工程文件，输出是 .kicad_pro / .kicad_sch / .kicad_pcb 文件集合，中间所有映射规则都可以用参数或配置文件控制。这样一来，你可以写一个 for 循环批量处理整个目录下的工程，也可以把转换命令写进 Jenkins 或 GitHub Actions，每次提交 EasyEDA Pro 工程后自动生成 KiCad 版本。

另一个容易被忽略的价值是差异对比。KiCad 的工程文件是文本格式，转换完以后你可以直接放进 Git 做 diff，看看这次转换改了什么、哪个焊盘漂移了、哪个网络断了。这一点是图形界面转换几乎做不到的。

2. 工具安装与环境准备

2.1 获取 epro2kicad 的几种方式

epro2kicad 不是 KiCad 自带的组件，所以要先安装。从我的经验来看，它比较常见的发布方式是通过 Git 仓库分发源码，需要你自己克隆代码后安装依赖，也可能直接发布了 Python 包或 Rust 二进制。我这次用的是 Python 版本，整个安装过程没有遇到编译障碍，相对省心。

如果你习惯从源码跑，典型步骤是:

git clone https://github.com/your-epro2kicad-repo/epro2kicad.git cd epro2kicad pip install -r requirements.txt python -m epro2kicad --version

如果项目发布了包，也可以直接通过 Python 包管理器安装。不同环境会略有差异，但通常不会要求你手动编译 C 扩展，所以整体安装成本很低。

2.2 依赖与运行要求

以 Python 实现为例，我建议在 Python 3.9 以上的环境里运行。它依赖的库包括解析 JSON 用的标准库、处理命令行参数用的 click 或 argparse、以及一些文件处理和日志库。此外，如果工具支持读取加密或者压缩过的工程包，可能还会依赖解压库。反正我自己的建议是，在开始转换之前先建一个虚拟环境，避免和系统里其他 Python 工具打架。

KiCad 本身也需要安装，而且要保证版本不能太旧。epro2kicad 输出的工程格式是 KiCad 6 以后的 s-expression 格式，如果你电脑上还只有 KiCad 5，可能打不开生成的工程。这也是我后面反复强调版本匹配的原因。转换工具在生成文件时通常会按照某个目标版本来组织内容，版本不一致很可能会出现"格式虽然生成了，但打开就报错"的情况。

2.3 快速验证安装

装好以后不要急着转大工程，先跑一下帮助命令确认工具正常：

epro2kicad --help

正常能看到子命令列表，比如 convert、inspect、list-layers 之类。然后再准备一个最小的测试工程，最好是新建一个只有一个原理图页、一个 PCB 的简单项目，先跑一遍完整转换，确认打开后的 PCB 至少能正常显示，再去处理复杂的板子。这一步能帮你把问题和工具本身的 bug 区分开。

3. 核心命令详解与转换实操

3.1 基本转换命令

最核心的命令是 convert，基本的用法非常直白：

epro2kicad convert ./demo.epro -o ./kicad_out

命令行里的 demo.epro 是 EasyEDA Pro 的工程文件，kicad_out 是输出目录。执行完以后，输出目录里会多出配套的工程文件。如果你的 EasyEDA Pro 工程是原理图和 PCB 一体的，那么转换后会同时生成原理图文件和 PCB 文件，不需要分别指定。

第一次跑的时候，我建议打开日志输出，观察每条转换信息：

epro2kicad convert ./demo.epro -o ./kicad_out --verbose

日志里会明确告诉你当前在解析什么对象、映射哪一层、跳过哪个封装。这一步特别重要，因为你能够看到工具在哪些地方做了取舍，哪些东西被丢弃了。很多工程师拿到转换结果后直接打开 KiCad，看到一堆封装缺失、网络丢失，就开始骂工具不行。其实工具早就打了警告，只是你开着默认日志没看。

3.2 常用参数与映射配置

epro2kicad 的转换参数里，我实际用得最多的是下面这几个：

这个表格看起来简单，但实际用起来每个参数都可能影响最终结果。尤其是 --format 这个参数，我曾经在一台只装了 KiCad 7 的机器上，回忆着默认值没管就直接转。工具默认生成的是它自己批次对应的目标版本，结果转完的 .kicad_pcb 打开就报解析错误。后来强制指定 --format 7 重新转换，问题立刻消失。

3.3 一个完整实例的转换记录

我自己最先拿来做测试的是一块双电机驱动板，板子上有两颗大功率 MOS、一组 H 桥、若干限流电阻和各种接插件。转换命令如下：

epro2kicad convert ./motor_driver.epro -o ./motor_driver_kicad --format 7 --verbose

转换过程比我想象的快，一个三四十个元件的板子大概两三秒就完成了。日志里能看到它在读取 .epro 工程数据，然后逐层扫描 PCB 的形状、覆铜、丝印、钻孔文件。生成的文件包括:

• motor_driver.kicad_pro（KiCad 工程文件）
• motor_driver.kicad_sch（原理图文件）
• motor_driver.kicad_pcb（PCB 文件）
• motor_driver.kicad_prt（如果版本支持）等

打开 PCB 后，板子外形、走线、焊盘基本都在。但我也发现丝印层上不少文本变成了默认字体，以前在 EasyEDA Pro 里用中文标注的"电源输入""电机A"这些字符串，在 KiCad 里要么变成问号要么变成方框。这是字体映射的问题，后面我会专门讲。

3.4 转换结果的目录结构

转换成功后，建议不要直接把输出目录里的文件拖出来乱放。KiCad 工程通常是一个目录加若干工程文件的结构，你最好让 .kicad_pro、.kicad_sch、.kicad_pcb 保持同一个目录。如果工具还输出了封装备份和缓存目录，也不要急于删掉，因为这些文件对于后续同步元件库非常有用。

有一个细节：KiCad 的 .kicad_sch 和 .kicad_pcb 都是文本文件，转换完之后你可以用文本编辑器打开，确认网络名、焊盘坐标、覆铜区域是否合理。第一次看到这么直观的 EDA 工程，我是有点震惊的，配合文本搜索定位某个网络名，比在图形界面里找快多了。这也是我强烈建议硬件工程师适应 KiCad 格式的原因之一。

4. 转换原理与映射规则

4.1 从 epro 的 JSON 结构说起

要理解 epro2kicad 为什么能转，为什么要这么转，得先看看 EasyEDA Pro 工程文件的内部结构。简单来说，.epro 是一个容器，里面用 JSON 描述了原理图页面的符号、连线、网络标签、PCB 里层的图形、走线、过孔和整板信息。工具做的第一件事，不是直接把它当成 PCB 文件去读，而是先解包、解析 JSON，再建立一套中间数据模型。

这个中间数据模型很重要。它有点像翻译过程中的"语义层"，先把 EasyEDA Pro 里的对象变成中性的元器件、网络、层、封装描述，然后再把这些描述输出成 KiCad 的 s-expression。好处是，将来 EasyEDA Pro 改版了，工具作者只要改前端的解析器，而不用重写 KiCad 生成器。

4.2 层、封装、焊盘的映射逻辑

PCB 的层映射是转换里最核心的部分。EasyEDA Pro 的信号层命名和 KiCad 不一样，工具需要按照默认规则把 EasyEDA Pro 的顶层对应到 F.Cu，底层对应到 B.Cu，中间信号层对应到 In1.Cu 到 In30.Cu。丝印层也是一样，顶层丝印对应 F.Silkscreen，底层丝印对应 B.Silkscreen。如果板子上有机械层或者开窗层，工具一般会映射到 KiCad 的 Edge.Cuts 或 User.Drawings，但这部分就要小心了，因为不同的 EasyEDA Pro 版本对开窗层的使用习惯并不一致，转换后必须人工核对。

焊盘的映射要复杂一些。EasyEDA Pro 里的焊盘形状有圆形、方形、圆角矩形、异形焊盘等，KiCad 的焊盘模型虽然也有类似描述，但参数细节不一样。比如同样是矩形焊盘，EasyEDA Pro 通过角半径、宽度、高度描述，KiCad 可能还要关心焊盘旋转角度、相对位置。工具转换的时候，如果直接把字段搬过去，很可能出现角半径丢失或者旋转量差异，这在连接器焊盘上尤其常见。我看到的现象是，排针、贴片电阻电容这类简单封装基本能完美转换，而带有圆形挖空、异形散热焊盘的封装，转出来之后需要手工修一下。

封装映射又是另一个坑。EasyEDA Pro 里元件引用的封装名往往带了立创库的命名特征，比如"CAP-TH_5x11mm"这种，KiCad 自带库里未必有同名的封装。工具通常提供两种策略：一是尝试根据尺寸参数自动生成封装文件，二是把缺失的封装记录到日志里，让你在 KiCad 里手动补。我个人更偏好第二种，至少不会出现装错封装的风险。

4.3 一定会丢的东西

任何转换工具都不可能 100% 无损，epro2kicad 也一样。常见的丢失项包括：

• EasyEDA Pro 的私有属性字段，比如自定义的 BOM 参数、采购链接、制造商编号
• 部分 3D 模型路径，尤其是立创商城自带的 step 模型关联
• 文档级设置，比如图纸模板、自定义标题栏
• 复用模块和子图逻辑，如果原理图里用了大量模块复用，转换后很可能会被展开成普通图块
• 中文文本的原始字体样式

理解这些丢失项不是为了劝退你，而是为了在转换前做好心理准备。我的原则是：PCB 的物理连接、覆铜、走线、焊盘这些决定电路能否工作的信息，优先级最高；丝印上的中文标注、自定义属性这些锦上添花的信息，转完再花时间补，不值得在转换前花大量时间做格式对齐。

5. 常见问题排查与避坑清单

5.1 封装库缺失怎么办

这是我最常被问的问题，也是转换后打开 KiCad 第一眼最容易发现的毛病：一堆封装修补符。处理原则很简单，先判断这个封装是不是标准封装。

如果是标准封装，比如 0805 电阻电容、SOT-23 晶体管、DIP-8 芯片，你直接在 KiCad 自带的库列表里搜索替换就行，不需要从 EasyEDA Pro 那边挣扎。如果不是标准封装，而是定制化的异形封装，建议把 EasyEDA Pro 里对应的封装信息导出，然后在 KiCad 封装编辑器里照着参数重新画一个。千万不要图省事随便找尺寸相近的封装顶上，热焊盘或散热焊盘尺寸差一点，生产就可能出问题。

如果你想批量处理，可以利用工具提供的 --map-file 参数，把 EasyEDA Pro 的封装名映射到 KiCad 的标准库封装名。比如：

{ "RES-0805": "Resistor_SMD:R_0805_2012Metric", "CAP-0805": "Capacitor_SMD:C_0805_2012Metric" }

这种映射文件一次配置，以后所有工程都能复用。我后来把项目里常用的五十多个封装都整理到了映射文件里，转换旧工程的速度明显快了很多。

5.2 字体乱码与汉字标注

转换后打开原理图或 PCB，最扎眼的就是原先的中文标注变成了一串方框。原理很简单，KiCad 默认的西文字体不含中文字形，而 EasyEDA Pro 里你用的中文字体在 KiCad 里根本不存在。

解决方案有三个层次。第一个层次是治标：把不在丝印层的中文注释删掉，把需要在板子上体现的标注改成英文，比如"电源输入"改成"PWR IN"。生产上大多数丝印标注用英文完全够用，还能让板子更整洁。第二个层次是治本：如果是原理图里的中文注释，在 KiCad 里用文本工具重新录入，借助系统字体渲染，显示没问题。第三个层次是给工具做字体映射，让转换后的文本使用一个支持中文的字体文件。不过老实说，这条路径并不总是可靠，因为 KiCad 本身对自定义字体的把持比较严格，你最终可能还是要接受手工调整。

5.3 网络丢失和覆铜异常

转换后网络丢失，多半不是工具把网络线弄丢了，而是网络名的映射规则出了问题。比如 EasyEDA Pro 里一个网络叫"VCC_5V0"，在 KiCad 里可能因为非法字符或长度限制被截断，导致原本应该连接的网络被分成了两个弱连接域。出现这种问题时，你可以在 .kicad_pcb 文件里搜索网络名，看看是否有类似截断的字符串。

覆铜是另一个高频雷区。转换后的覆铜区域不是自动填充状态，里面的热焊盘连接和网格线都需要在 KiCad 里重新执行一遍覆铜填充。这是 KiCad 的正常行为，不是 bug。你打开 PCB 编辑器，按一下 B 键（或菜单里的 Fill All Zones），覆铜才会真正铺出来。另外，转完以后覆铜与焊盘的连接方式可能还是 EasyEDA Pro 的散热连接设置，如果生产厂家反馈铜皮连接异常，优先检查覆铜热焊盘的规则。

5.4 焊盘和过孔参数对不上

焊盘尺寸对不上，最常见的原因是单位换算或精度舍入。EasyEDA Pro 默认单位有时是 mm，有时在描述毫米小数四舍五入后，KiCad 里以纳米单位保存就会出现细微偏差。解决办法是，不要逐个焊盘去改，而是先看全局的尺寸公差：如果所有贴片焊盘都小了 0.01mm，那大概率是精度丢失，不是个别错误。

过孔方面也有一个容易踩的坑：EasyEDA Pro 里的盲埋孔定义和 KiCad 的层对结构不同，转换后盲埋孔可能被当成普通通孔处理，导致生产文件层面出现问题。如果你板子上有盲埋孔，转换后一定要逐层检查孔信息，确认 Start Layer 和 End Layer 正确。

5.5 转完打不开或报错

打开就报错的情况，九成是 KiCad 版本和目标格式不匹配。KiCad 6 工程的文件和 KiCad 7、8 并不完全兼容，你在命令行指定 --format 的时候，要严格用你电脑上实际安装的那个 KiCad 版本号。如果开了新版本 KiCad，预备把旧工程打开再自动升级，也不一定 100% 成功，所以最好第一次就指定正确版本。

还有一类打不开的原因是输出路径下的文件名带了中文或空格。KiCad 对工程路径中的非英文字符不算友好，我遇到过一次因为工程名带了个中文括号，导致原理图和 PCB 关联不上的诡异问题。建议转换输出前，把工程命名统一改成英文字母、数字、下划线组合。

6. 这些场景用起来特别值

6.1 批量迁移历史工程

前面说的都是单个工程转换，但 epro2kicad 真正的威力在批量处理。比如你有一个目录，里面存着几十个 EasyEDA Pro 工程，每个工程都有自己的 .epro 文件，你可以用 shell 脚本一把梭：

for f in ./projects/*.epro; do dir="./kicad_out/$(basename "$f" .epro)" mkdir -p "$dir" epro2kicad convert "$f" -o "$dir" --format 7 --verbose done

这个脚本看着简单，但有几个细节要注意。一是每个工程单独输出目录，避免文件互相覆盖。二是建议脚本里面加个循环内的日志，把转换成功和失败的工程名分别记录下来，方便批量跑完后集中处理。我第一次批量跑的时候，以为全程顺利，结果后面打开一批文件才发现有几块板子的丝印层被映射成了内层，原因就是那几个工程使用了不常见的机械层命名。所以批量跑完后必须抽查。

6.2 在 CI 里做格式校验

如果你的团队已经开始用 Git 管理硬件工程，epro2kicad 还能扮演"格式校验员"的岗位。可以在 push 或者 tag 时触发一个任务，把 EasyEDA Pro 工程转换到 KiCad 格式，并在转换失败时阻止合并。这样，就算团队里有人仍然用 EasyEDA Pro，也不会影响其他人用 KiCad 协作。

我搭过的流程很简单：CI 容器里装好 Python、克隆 epro2kicad 代码、安装依赖，然后跑一条转换命令，最后用 git diff 检查生成的工程文件有没有实际变化。整个过程没有任何图形界面，非常适合在服务器环境跑。

6.3 团队协作里减少"工具锁死"

硬件团队常常会遇到一个问题：少数人习惯 KiCad，少数人习惯 EasyEDA Pro，图纸交给另一边就完全打不开。过去遇到这种情况，只能让人手动导出文件，既麻烦又容易带丢数据。有了命令行转换流程之后，团队可以约定：EasyEDA Pro 工程为原始输入，KiCad 工程为发布输出，每次变更通过转换命令生成新的 KiCad 版本。版本管理里同时保留两种格式，谁都能打开，谁都能审查。

而且 KiCad 工程是文本化的，code review 的时候可以直接看网络的增删、元件的替换，这在以前用私有格式时是完全不敢想的。我自己在实际操作后的体会是：转换工具有没有用，不在于它能不能把每个细节都完美搬过来，而在于它能不能把"换工具"这件事从"手动熬夜"变成"自动巡检"。epro2kicad 离完美还差得远，但方向已经对了：所有能交给命令行的，就不要交给鼠标。