Git 在硬件项目中的使用：原理图/PCB 版本管理实战指南

为什么硬件项目也需要 Git？

做软件的朋友可能无法理解：硬件设计不就是画个图、布个板子吗？要什么版本控制？

直到有一天，你改了个电阻值，发现板子不工作了，想回退却找不到原来的文件；或者团队协作时，两个人同时改了原理图，最后不知道用谁的版本……

这时候你就明白了：硬件设计也是代码，也需要版本管理。

今天我们就来聊聊，如何用 Git 管理硬件项目，特别是 KiCad、Eagle 这些 EDA 工具生成的文件。

需要准备什么？

物品	型号/规格	价格
电脑	任意 Linux/Mac/Windows	已有
EDA 工具	KiCad 7.x（推荐）	免费
Git	2.x 以上版本	免费
代码托管	GitHub/Gitee	免费
总计		¥0

是的，这套工具链完全免费！KiCad 是开源 EDA 工具，Git 也是开源的，GitHub 个人仓库免费。

步骤 1：Git 基础配置

首先安装 Git（如果还没装）：

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install git

# macOS
brew install git

# Windows
# 下载 https://git-scm.com/download/win

配置你的身份信息：

git config --global user.name \"Your Name\"
git config --global user.email \"your.email@example.com\"

# 推荐：设置默认分支为 main
git config --global init.defaultBranch main

# 推荐：启用彩色输出
git config --global color.ui auto

步骤 2：硬件项目的 Git 结构

硬件项目和软件项目有个很大的不同：有很多二进制文件（Gerber、PDF、3D 模型等）。这些文件不适合做差异比较，但需要版本追踪。

推荐的项目结构：

my-hardware-project/
├── .gitignore          # Git 忽略文件配置
├── README.md           # 项目说明
├── docs/               # 文档
│   ├── BOM.md          # 物料清单
│   └── assembly.md     # 组装说明
├── hardware/           # 硬件设计文件
│   ├── schematic/      # 原理图
│   │   └── project.kicad_sch
│   ├── pcb/            # PCB 布局
│   │   └── project.kicad_pcb
│   └── lib/            # 元件库
├── firmware/           # 固件代码
│   └── src/
├── gerber/             # 生成的 Gerber 文件
└── 3d-models/          # 3D 模型文件

步骤 3：编写 .gitignore

这是最关键的一步！EDA 工具会生成很多临时文件和备份文件，我们不需要追踪它们。

KiCad 项目的 .gitignore 示例：

# KiCad 自动生成的备份文件
*-backup.kicad_sch
*-backup.kicad_pcb
*.kicad_sch-bak
*.kicad_pcb-bak

# KiCad 缓存和临时文件
cache/
tmp/
*.cache

# 自动生成的输出文件（可选，看团队需求）
gerber/
production/
*.pdf
*.step
*.wrl

# 编辑器临时文件
.vscode/
.idea/
*.swp
*.swo
*~

# 操作系统文件
.DS_Store
Thumbs.db

注意： Gerber 文件是否纳入版本控制，取决于你的团队策略。如果每次提交都包含 Gerber，仓库会变大；如果不包含，每次发布需要重新生成。我的建议是：开发阶段不提交 Gerber，发布标签（tag）时生成并附带。

步骤 4：初始化仓库并提交

# 创建项目目录
mkdir my-hardware-project
cd my-hardware-project

# 初始化 Git 仓库
git init

# 创建 .gitignore
cat > .gitignore  README.md 100mV）

差的示例：

更新 PCB

步骤 6：处理二进制文件

KiCad 的 .kicad_pcb 文件本质上是文本格式（S-表达式），可以做差异比较。但有些文件是纯二进制的（如 3D 模型、图片）。

查看 PCB 文件差异

# KiCad PCB 文件可以用 git diff 直接查看
git diff hardware/pcb/project.kicad_pcb

# 输出示例：
- (segment (start 100 100) (end 150 100) (width 0.25) (layer \"F.Cu\"))
+ (segment (start 100 100) (end 150 100) (width 0.5) (layer \"F.Cu\"))

可以看到线宽从 0.25mm 改成了 0.5mm。

二进制文件的 Git LFS 支持

如果项目有很多大文件（3D 模型、高清图片），建议使用 Git LFS：

# 安装 Git LFS
git lfs install

# 追踪大文件类型
git lfs track \"*.step\"
git lfs track \"*.wrl\"
git lfs track \"*.png\"

# 这会修改 .gitattributes 文件
git add .gitattributes
git commit -m \"配置 Git LFS 追踪 3D 模型和图片\"

注意： GitHub 免费账户 LFS 有 1GB 配额，超出需要付费。

步骤 7：团队协作与代码审查

使用 Pull Request/Merge Request

1. $1

2. $1

3. $1

4. $1

5. $1

原理图审查技巧

KiCad 可以导出原理图为 PDF 用于审查：

# 导出原理图 PDF
kicad-cli sch export pdf \\
  -o docs/schematic-v1.2.pdf \\
  hardware/schematic/project.kicad_sch

# 将 PDF 附加到 PR 描述中供审查

或者使用 KiCad 的”比较原理图”功能，可视化查看两个版本的差异。

常见问题排查

问题 1：KiCad 文件提交后无法打开

• 原因： 可能是文件编码问题或未完整提交

• 解决： 确保 .kicad_sch 和 .kicad_pcb 文件完整提交，不要拆分；使用 git lfs 追踪大文件

问题 2：合并冲突怎么处理？

• 原因： 两个人同时修改了同一个文件

• 解决：

用文本编辑器打开冲突文件

• 找到 >>>>>> 标记

• 手动选择保留的变更

• 在 KiCad 中打开验证

• 提交解决后的文件

• 预防： 团队成员分工明确，避免同时修改同一模块

问题 3：仓库太大怎么办？

• 原因： 提交了太多大文件或历史版本累积

解决：

# 检查仓库大小
git count-objects -vH

# 清理未引用的对象
git gc --prune=now

# 如果 Gerber 等输出文件太大，从历史中移除
git filter-branch --tree-filter \'rm -rf gerber/\' HEAD

问题 4：如何回退到之前的版本？

解决：

# 查看历史提交
git log --oneline

# 回退到某个提交（保留工作区变更）
git checkout 

# 或者创建回退提交
git revert 

总结

用 Git 管理硬件项目的好处：

1. $1

2. $1

3. $1

4. $1

5. $1

最佳实践总结：

• 写清楚 .gitignore，避免提交临时文件

• 提交信息要详细，说明”改了什么”和”为什么改”

• 大文件用 Git LFS 管理

• Gerber 等输出文件在发布时生成，用 tag 标记

• 定期 git gc 清理仓库

希望这篇博客文章对您有所帮助！

---

相关资源：

• Git 官方文档

• KiCad 版本控制最佳实践

• Git LFS 使用指南

• GitHub 硬件项目示例