## 为什么硬件项目也需要 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（如果还没装）：
“`bash
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install git
# macOS
brew install git
# Windows
# 下载 https://git-scm.com/download/win
“`
配置你的身份信息：
“`bash
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` 示例：
“`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：初始化仓库并提交
“`bash
# 创建项目目录
mkdir my-hardware-project
cd my-hardware-project
# 初始化 Git 仓库
git init
# 创建 .gitignore
cat > .gitignore << 'EOF'
*-backup.kicad_sch
*-backup.kicad_pcb
cache/
tmp/
*.cache
gerber/
*.pdf
.DS_Store
EOF
# 创建 README.md
cat > README.md << 'EOF'
# 我的硬件项目
## 简介
这是一个基于 STM32 的开发板项目。
## 硬件
- MCU: STM32F103C8T6
- 电源：5V USB 供电
- 接口：USB-C, SWD 调试口
## 软件
- KiCad 7.x
- 固件：PlatformIO + Arduino Framework
## 编译 Gerber
```bash
cd hardware/pcb
kicad-cli pcb export gerber -o ../../gerber project.kicad_pcb
```
EOF
# 首次提交
git add .
git commit -m "初始提交：项目结构和文档"
```
## 步骤 5：硬件设计的版本控制工作流
### 日常开发流程
```bash
# 1. 开始新功能前，创建分支
git checkout -b feature/add-usb-c-connector
# 2. 在 KiCad 中修改原理图/PCB
# 3. 查看变更
git status
git diff hardware/schematic/project.kicad_sch
# 4. 提交变更（写清楚改了什麼）
git add hardware/schematic/project.kicad_sch
git commit -m "原理图：添加 USB-C 接口和 ESD 保护
- 添加 TYPE-C-31-M-12 连接器
- 添加 PESD5V0S1UL 保护二极管
- 更新 VBUS 网络标签
参考：USB-IF Type-C 规范 1.3"
# 5. 推送到远程
git push origin feature/add-usb-c-connector
```
### 提交信息规范
硬件项目的提交信息建议包含：
- **文件类型**：原理图/PCB/封装库
- **改动内容**：添加了什么、修改了什么
- **原因**：为什么改（需求/问题修复）
好的示例：
```
PCB：优化电源走线，降低 EMI
- 加宽 5V 主电源走线至 0.5mm
- 添加去耦电容靠近 IC 引脚
- 分离模拟/数字地平面
原因：第一版测试发现 3.3V 纹波过大（>100mV）
“`
差的示例：
“`
更新 PCB
“`
## 步骤 6：处理二进制文件
KiCad 的 `.kicad_pcb` 文件本质上是文本格式（S-表达式），可以做差异比较。但有些文件是纯二进制的（如 3D 模型、图片）。
### 查看 PCB 文件差异
“`bash
# 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：
“`bash
# 安装 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. 开发者在本地创建功能分支
2. 完成后推送到远程仓库
3. 在 GitHub/Gitee 上创建 Pull Request
4. 团队成员审查变更（特别是原理图和 PCB）
5. 审查通过后合并到主分支
### 原理图审查技巧
KiCad 可以导出原理图为 PDF 用于审查：
“`bash
# 导出原理图 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：合并冲突怎么处理？**
– **原因：** 两个人同时修改了同一个文件
– **解决：**
1. 用文本编辑器打开冲突文件
2. 找到 `<<<<<<<` 和 `>>>>>>>` 标记
3. 手动选择保留的变更
4. 在 KiCad 中打开验证
5. 提交解决后的文件
– **预防：** 团队成员分工明确，避免同时修改同一模块
**问题 3：仓库太大怎么办？**
– **原因：** 提交了太多大文件或历史版本累积
– **解决：**
“`bash
# 检查仓库大小
git count-objects -vH
# 清理未引用的对象
git gc –prune=now
# 如果 Gerber 等输出文件太大，从历史中移除
git filter-branch –tree-filter ‘rm -rf gerber/’ HEAD
“`
**问题 4：如何回退到之前的版本？**
– **解决：**
“`bash
# 查看历史提交
git log –oneline
# 回退到某个提交（保留工作区变更）
git checkout
# 或者创建回退提交
git revert
“`
## 总结
用 Git 管理硬件项目的好处：
1. **版本可追溯**：随时知道谁在什么时候改了什么
2. **协作更高效**：多人同时开发不冲突
3. **变更可审查**：Pull Request 机制保证质量
4. **备份更安全**：远程仓库防止本地丢失
5. **发布可重现**：每个版本都有对应的代码和硬件设计
**最佳实践总结：**
– 写清楚 `.gitignore`，避免提交临时文件
– 提交信息要详细，说明”改了什么”和”为什么改”
– 大文件用 Git LFS 管理
– Gerber 等输出文件在发布时生成，用 tag 标记
– 定期 `git gc` 清理仓库
希望这篇博客文章对您有所帮助！
—
**相关资源：**
– [Git 官方文档](https://git-scm.com/doc)
– [KiCad 版本控制最佳实践](https://docs.kicad.org/)
– [Git LFS 使用指南](https://git-lfs.com/)
– [GitHub 硬件项目示例](https://github.com/topics/hardware)