apio FPGA 开源工具链实测：一个 523MB 包装下 109 块板卡

《FPGA 每日开源更新》第 83 期，这次聊 apio（FPGAwars/apio）。一个 523 MB 的包，解压开就是 yosys、nextpnr、iverilog、GTKWave，还带着 109 块开发板的引脚定义。装它只需要一行 pip。

一、apio 是什么？

apio 是一套命令行 FPGA 工具套件，第一个提交在 2016 年 2 月，到今天整十年。它管的是开发里最琐碎的那一段：装工具、找引脚、拉示例。

环境配置这件事，它能解决得非常省心。为了点一颗 LED，先下几十个 GB 的厂商 IDE，配 license，等两小时——这种事大家应该都干过。apio 把这条路径压成两条命令。

GPL-3.0，Windows、Linux、macOS 都有，Python 3.11 到 3.14。我本机装的是 1.6.0，pip 一条命令装完，顺带拖进来 43 个 Python 依赖。

它卖的不是综合器，是一个装好就能用的状态。

二、特别的一点是把板卡世界装进一个包

这是全篇唯一要你记住的事。

apio 分两层。CLI 本体是个 Python 包，用 pip 安装；工具链、板卡定义、示例工程是 apio 自己管理的包，装在 APIO_PACKAGES 目录里。这套“包里有包”的结构，是它和手工装 oss-cad-suite 最大的差别。

我把它装完的 definitions 包拆开数了一遍。boards.jsonc 里是 109 块开发板定义，fpgas.jsonc 里是 96 个 FPGA 器件，programmers.jsonc 里是 13 个烧录器。iCE40、ECP5、Gowin，加上 AMD-Xilinx 7 系列，四个家族都在这份表里。

示例也在同一个包里，111 个可以直接拉取的工程，分布在 58 个板卡目录下。想点灯就拉点灯，想看 PLL 就拉 PLL。

工程描述只有两行，一个 apio.ini 写清板和顶层模块，换板子改一行就够。

工具链那侧更有意思。

fpgawars 把这些包做成了日构建，oss-cad-suite 的 release 标签从 2026-09-15 起，09-20 到 09-25 连着出，一天一个。但线上配置只指向 09-15 那一个。我去 GitHub 上核了下载量，后面这六个，下载数都是 0。

配置指向哪个，用户才拉哪个。剩下的都是留给自己的回滚位。

三、四块板，同一套命令

官方示例我拉了四个板子，走的是同一条路：apio examples fetch <板卡>/<示例>，然后 apio build。

iCE40 的 icestick 点灯工程 2.41 秒出 31 KB 的 .bin，占 1 个逻辑单元。

ECP5 的 IcePi Zero，就是第 77 期那块 79 美元的板子，5.91 秒出 97 KB 的 .bit，33 个 COMB 加 26 个触发器。ulx3s 45F 用时 3.14 秒。

最值得说的是 Artix-7。arty-a7-35t 13.08 秒出了 2141 KB 的 .bit，中间是 yosys 综合、nextpnr-xilinx 布局布线、fasm2frames、xc7frames2bit 四步，全程没有 Vivado 参与，芯片数据库它自己下载并校验了 checksum。

apio report 再花 0.34 秒，把资源占用和时序打成一张表。apio sim 5.5 秒跑完 testbench 出 .vcd，不加 --no-gtkwave 就直接弹窗给你看波形。

这几块板跑的都是几十个 LUT 的点灯电路，报告里的最高时钟只说明工具链会算时序，不代表器件性能，别拿去横向比。

四、怎么用上，以及有哪些坑

说实话，那 523 MB，我这台 Windows 笔记本直连没下下来。

第一道墙更靠前。apio 启动要读一份远程配置，地址指向 GitHub 的 raw.githubusercontent.com。我这边连不上，apio boards 直接报错退出，连“列出支持的板子”都跑不了。绕行是把 APIO_REMOTE_CONFIG_URL 指到 CDN 镜像。

第二道墙是那个包。apio packages install 前面几个小包都顺利，轮到 oss-cad-suite 时连接被掐断，进程直接退出。根因在它的设计上：apio 每条命令启动时都会检查一遍缺失的包，缺了就补装，失败就整个终止。好处是装完就能用、不用操心；代价是把“首次可用”和“GitHub 可达”绑死了。

绕行有三条。挂代理最省事，requests 认 HTTPS_PROXY；没有代理就用能续传的下载器把 tgz 拉下来，解压到 APIO_PACKAGES 并登记 installed_packages.json，我最后就是这么过去的；再退一步，用 YosysHQ 官方的 oss-cad-suite。

第三个坑是命令改名，0.9.5 到 1.x 改了十条，apio verify 变成 apio lint，testbench 里的 $dumpfile() 也得删。许可上，apio 本体 GPL-3.0 有传染性，它打包的工具链以各自许可为准。

最后划一条边界。第 79 期推过的 fusesoc 管的是 IP 核怎么拼成一个工程，apio 管的是工具链和板卡怎么装起来。

五、仓库信息卡

• 仓库：github.com/FPGAwars/apio
• Stars / Forks：1009 / 170（抓取 2026-09-26）
• 首次提交：2016-02-09，距今十年
• 最近提交：2026-09-25
• 许可证：GPL-3.0
• 语言：Python（CLI 本体）
• 贡献者：54 人，其中 zapta 一个人 2425 次提交
• 本机实测：Windows，Apio CLI 1.6.0（pypi-2026-09-15）

谁该看：手上有 iCE40、ECP5、Gowin 或 Artix-7 板子，想用开源工具链又不想配环境的人；一块板子要迭代几十次、希望环境只装一次的人。

谁别碰：必须在厂商 IDE 里跑时序收敛和 IP 集成的人；只做 ASIC 流程、不关心板卡引脚的人。

需要注意的是：它把配环境这件事从工作流里整段删掉了，代价是这 523 MB 你得自己想办法下下来。

仓库地址：github.com/FPGAwars/apio。手上有小容量 FPGA 板子的话，装一次试试，比手工拼工具链省事。