企业官网建设流程全解析

SuperPower硬件文档自动化：kiplot+GitHub Actions自动生成ERC/DRC检查与PCB渲染完整教程

【免费下载链接】SuperPowerHere you should find the best power supplies for your low-power projects项目地址: https://gitcode.com/gh_mirrors/sup/SuperPower

SuperPower 是一个面向树莓派与低功耗微控制器的开源硬件电源项目，它用 KiCad 完成电路设计，并通过kiplot + GitHub Actions实现硬件文档自动化：每次修改原理图或 PCB 文件，自动运行 ERC/DRC 检查、导出 PDF/SVG 文档并渲染 PCB 图。本文带你完整配置这条自动化流水线，让硬件文档和检查报告"零手动"产出。

项目背景：SuperPower 电源设计的文档痛点

SuperPower 包含两块板卡：

• SuperPower-RPi：为树莓派供电的电源板
• SuperPower-uC：面向 ESP32 等低功耗微控制器的电源板（含 original 与 lowcost 两个版本）

三套 KiCad 工程意味着每次改动都要重复繁琐的工作：手动跑 ERC、手动跑 DRC、手动导出原理图和 PCB 图、再手动更新文档。SuperPower 的解法是把这一切交给 CI，核心只有两个文件：

快速上手：克隆仓库与自动化相关文件清单

先克隆项目（仓库地址如下）：

git clone https://gitcode.com/gh_mirrors/sup/SuperPower cd SuperPower

自动化相关文件一览：

config.kiplot.yaml # kiplot 全局配置 .github/workflows/kicad-export.yml # CI 工作流 SuperPower-RPi/SuperPower-RPi-KiCAD/ # 树莓派电源板工程 SuperPower-uC/original/ # MCU 电源板（标准版） SuperPower-uC/lowcost/ # MCU 电源板（低成本版） .generated/ # 自动生成的文档与报告 build/ # CI 上传的产物目录 sphinx/ # 文档站点（直接引用生成图）

💡 记住这个套路：一个 yaml 配置 + 一个 workflow 文件，就能把任意 KiCad 项目接入同样的自动化流程。

配置 kiplot：一键完成 ERC/DRC 检查与 PCB 渲染

config.kiplot.yaml 分为两大块：preflight（检查）和outputs（渲染导出）。

preflight：自动运行 ERC、DRC 与铜皮检查

preflight: run_erc: true # 原理图电气规则检查 run_drc: true # PCB 设计规则检查 check_zone_fills: true # 检查铺铜是否失效 ignore_unconnected: false filters: - filter_msg: 'Pin connected to other pins, but not driven by any pin' error_number: 3 regexp: '(Power input) of component'

⚙️ 两个关键点：

• 检查全覆盖：ERC 管原理图连线错误，DRC 管 PCB 间距与规则，铜皮检查防止过孔断连。
• 误报过滤：filters允许对特定报错做正则白名单。SuperPower 中"电源输入引脚未被驱动"是设计使然，于是把 error 3 按(Power input) of component正则过滤掉，避免 CI 天天"假报警"。

outputs：原理图 PDF/SVG 与 PCB 渲染图

outputs: - name: 'Print Schema as PDF' type: pdf_sch_print # 原理图 -> PDF dir: schematics - name: 'Pront Schema as SVGs' type: svg_sch_print # 原理图 -> SVG（供文档引用） dir: schematics - name: 'print board' type: pdf_pcb_print # PCB -> PDF layers: 'all' dir: layout - name: 'plot images of pcb TOP' type: 'pcbdraw' # PCB 3D 风格 2D 渲染 options: dpi: 300 format: 'svg' style: '/opt/pcbdraw/pcbdraw/styles/jlcpcb-green-enig.json' - name: 'plot images of pcb BOTTOM' type: 'pcbdraw' options: bottom: true # 渲染底面

PcbDraw 输出的是 300 DPI 的高清 PCB 渲染图，风格指定为打板厂常见的绿色沉金配色，顶面、底面各一张，README 与文档开箱即用。

配置 GitHub Actions：原理图变更自动触发文档生成

工作流 .github/workflows/kicad-export.yml 的精华在于按文件路径精准触发——只有 KiCad 源文件变更才跑，节省 CI 资源：

on: push: paths: - '**.sch' # 原理图文件 - '**.kicad_pcb' # PCB 文件 pull_request: paths: - '**.sch' - '**.kicad_pcb'

任务体依次执行：

1. actions/checkout拉取代码
2. 三遍调用nerdyscout/kicad-exports动作，分别指向三套工程：

- uses: nerdyscout/kicad-exports@v2.0 name: kiplot-SuperPower-RPi with: config: config.kiplot.yaml dir: build/SuperPower-RPi schema: 'SuperPower-RPi/SuperPower-RPi-KiCAD/SuperPower-RPi-KiCAD.sch' board: 'SuperPower-RPi/SuperPower-RPi-KiCAD/SuperPower-RPi-KiCAD.kicad_pcb'

3. actions/upload-artifact将build/目录整体打包为产物"Generated Schematics and Layouts"

🚀 也就是说：提交一个.sch或.kicad_pcb改动 → CI 自动跑完 ERC/DRC + 全部渲染 → 产物可下载，全程无需人工干预。

查看自动产出：ERC/DRC 报告与 PCB 渲染图存放位置

CI 完成后，生成物落在.generated/下，按板卡分目录，例如树莓派板卡：

.generated/SuperPower-RPi/SuperPower-RPi-KiCAD.erc # ERC 报告 .generated/SuperPower-RPi/drc_result.rpt # DRC 报告 .generated/SuperPower-RPi/kiplot_errors.filter # 被过滤的报错清单 .generated/SuperPower-RPi/build/Pi-MCU-Pi-MCU.svg # 各页原理图 SVG .generated/SuperPower-RPi/build/Pi-Charger-Pi-Charger.svg

MCU 板卡的 PCB 渲染图同样自动生成：

.generated/SuperPower-uC/lowcost/layout/SuperPower-uC-KiCad-Board_top.svg .generated/SuperPower-uC/lowcost/layout/SuperPower-uC-KiCad-Board_bottom.svg

更妙的一环：Sphinx 文档站点直接引用这些生成图。例如sphinx/uc/low/overview_keep.rst中写入../../../.generated/SuperPower-uC/lowcost/schematics/l_charger.svg，于是文档里的电路图和 ERC/DRC 检查永远同步——PCB 一改，文档自动跟着变，不存在"文档过期"问题。

自动检查如何守住硬件文档质量

ERC/DRC 不只是"报错机器"，它还替你监督整个团队的绘图规范。SuperPower 在sphinx/project/guidelines.rst中定下了原理图规范，配合自动检查形成质量闭环。以下示例都来自该规范文档：

位号贴近元件、不与其他文字重叠，保持文本整洁

逻辑流向从左到右，正电源向上、地向下，同类符号保持同向

引脚按功能而非芯片物理位置摆放：输入在左、输出在右、VCC 在上、GND 在下

减少走线交叉、直接连接，让 ERC 报告更聚焦真实问题

当渲染出的 SVG/PDF 明显"不好看"时，说明设计偏离了规范；当 ERC/DRC 报告出现错误时，说明功能可能有问题。两者结合，硬件文档质量有了双重保障。✅

常见疑问：kiplot 自动化 FAQ

Q1：CI 里某个报错是设计意图，怎么办？在config.kiplot.yaml的preflight.filters中按"报错编号 + 正则"加白名单，被过滤的内容会记录在kiplot_errors.filter中，可追溯。

Q2：想换 PCB 渲染风格或分辨率？改pcbdraw输出的style（换成其他 JSON 配色）与dpi（10–1200 可选）即可，无需改动 workflow。

Q3：想让 ERC 有错就 CI 失败？kiplot 的preflight默认会把检查失败视为流程失败。若当前 CI 容忍告警，可结合 workflow 中 kiplot 的fail_on_error类参数收紧，实现"带病提交"零容忍。

Q4：多板卡项目如何扩展？照抄 workflow 中现有的 step，改name、dir、schema、board四个参数即可，SuperPower 的三块板就是这么跑出来的。

总结：把硬件文档交给 CI

回顾 SuperPower 这套硬件文档自动化的完整链路：

1. 写：config.kiplot.yaml声明"检查什么、渲染什么"
2. 触发：GitHub Actions 监听*.sch/*.kicad_pcb变更
3. 产出：ERC/DRC 报告 + 原理图 PDF/SVG + PCB 高清渲染图
4. 消费：Sphinx 文档直接引用生成图，文档与电路永不过期

整套方案只依赖两个 YAML 文件，任何 KiCad 硬件项目都可以照搬。让 CI 替你盯紧每一根走线、每一份文档，你只管专注电路设计本身。🔌

【免费下载链接】SuperPowerHere you should find the best power supplies for your low-power projects项目地址: https://gitcode.com/gh_mirrors/sup/SuperPower