画了十几年板子最怕的不是电路出问题而是改到第三版之后客户说“还是第一版那个方案好”。这时候如果你还在靠“_final”“_最终版”“_打死不改版”这类文件夹管理Altium Designer工程那恭喜你光找文件就够折腾一下午。Altium Designer本身是带版本控制功能的接上Git或SVN之后原理图、PCB、封装库都能纳入一套完整的历史管理体系改到哪一步都清清楚楚随时可以回到任何一个历史状态。这篇东西不是泛泛介绍概念而是把你真正会用到的配置流程、日常操作、协作规范和常见坑全部按实际踩过的顺序整理出来。适合自己一个人画板、也适合三五个人一起开发板卡的中小团队只要你不是坚持用U盘拷贝文件的极限流这套东西都能帮你省下大量重复劳动。1. 为什么硬件工程师需要自己的版本控制方案1.1 没有版本控制的硬件项目有多容易失控很多人觉得版本控制是写代码的人才需要的东西画板子嘛文件不大自己心里有数就行。这个想法在单人单板、原型验证阶段勉强成立但一旦项目进入改版期问题就来了。举个真实的例子。我之前做过一块四层ARM核心板第一次投板后根据实测反馈改了电源模块的布局又因为DDR走线长度匹配问题调整了两次PCB。加上最初发给工厂生产的版本不到一个月时间项目文件夹里就堆了七八版文件。后来客户说测试发现新版本在某些电压下有纹波异常想看看最初版本的实测表现我得挨个打开原理图对比是哪一版改了哪个电阻的阻值、哪一版调整了去耦电容的位置。那次之后我花了一个晚上把项目完整接入了Git后面再遇到类似情况直接一条命令看历史记录连当时提交时写的备注都比记忆靠谱。靠文件夹改名管理的另一个问题是多人协作时几乎必然产生“覆盖事故”。两个人同时改同一份PCB一个人把另一个人连续三天的布局调整全冲掉了这种事情在共用服务器或网盘的团队里并不少见。版本控制的核心价值不是“备份”而是“留痕”每个人改了什么、什么时候改的、为什么这么改全部有记录想回退随时回退。1.2 版本控制到底能帮你守住什么底线版本控制对硬件设计的作用可以概括成三条底线。第一时间维度的安全网。项目发展到任何阶段都可以回到过去任意一次提交时的状态。这个“任意”不是你自己靠命名的版本号猜的而是系统如实记录的。不管你是想找回删掉的模块还是对比当前布局和两个月前的差异都是分钟级的事情。第二改动归因的追溯链。当“这块电路是谁改的、为什么改”成为问题时版本控制的提交日志就能还原上下文。规范的提交说明可以记录“改DDR匹配电阻以优化信号完整性参考AN136 app note”这样即使过了半年你也能看懂当时的意图。第三并行开发的协调机制。分支是一种低成本的“平行宇宙”可以放心地在分支里做实验性改动失败了不影响主干成功了再合并回主干。这一点在改版风险较高的项目中特别实用。对于AD用户来说好消息是这些能力不用切出软件去学一堆命令行AD的版本控制接口把提交、更新、查看历史这些高频操作都做进了IDE里面几乎不怎么增加额外学习成本。2. 上手前必懂AD版本控制的几种形态和选型思路2.1 AD里能用的版本控制其实有两条路线Altium Designer对版本控制的支持从功能层面分为两条路线。一条是AD自身的历史备份机制也就是Local History。这个功能不需要外部软件它会按设定周期为你本地的文件生成历史快照存放在Local History目录下。严格来说这不算“版本控制”因为它没有提交权限、没有一个全局的版本树也不支持多人协作更像一份自动化的“后悔药”。AD在文件被外部程序覆盖或是你明显改动文件时会触发历史快照关键时候确实能救命但不能拿来当日常协作工具。另一条才是真正意义上的版本控制Version Control通过AD设置里的Version Control接口接入外部版本控制系统。AD天然支持两类VCSSVN和Git。SVN的历史比较悠久AD早年版本用得多Git则是当下更主流的选择尤其是AD 20之后的版本对Git的支持流畅度已经相当不错日常操作基本在Project面板里就能完成不用频繁敲命令。这两条路线不是互斥的我的建议是版本控制做主线Local History当作双保险两者同时开。2.2 SVN还是Git别纠结按这几点选初次接触AD版本控制的人第一反应往往是“那到底用SVN还是Git”我的回答很简单没有历史包袱的新项目直接用Git如果是公司已有SVN服务器、团队也都习惯SVN流程的维持SVN也没问题AD对两种VCS都支持得比较完整。核心是先把版本控制用起来工具本身的差异远没有想象中大。从原理上说SVN是集中式所有提交直接进中央服务器工作副本只是“取出”的文件Git是分布式每个人本地都有一份完整仓库可以离线提交再推送到远程。对硬件设计场景来说这个差异带来的实际体验区别主要是SVN会标记文件为“锁定”状态适合不常改动的文件Git则更灵活不锁文件靠合并流程保证一致性。但注意原理图和PCB文件本质上都是二进制格式没法像代码那样做行级合并所以即使是用Git同一时间最好也只有一个人改同一块PCB别指望手动合并两个不同人改的.PcbDoc。选型如果还拿不准给一个简单参考个人开发者或小团队没有任何服务器运维成本预算的选Git配合Gitee、GitHub私库或本机仓库都可以公司已经有集中式管理习惯、IT部门能维护SVN服务的继续用SVN也不会错。真正需要避开的坑是版本控制接了半天团队里没有固定工作流程结果大家还是各改各的最后照样冲突。2.3 认识AD的Version Control面板在用AD操作之前先认识一下界面上的几个关键位置。Projects面板是日常使用的核心入口项目树里每个文件都有状态图标绿色勾表示本地与版本库一致橙色标记表示文件被修改过但还没提交蓝色加号通常表示新增文件尚未纳入版本控制。把目光移到Project面板底部的Version Control标签页这里面会展示选定文件或整个项目的版本状态、当前版本号、锁定标记、修改时间等信息。这个面板相当于VCS状态的仪表盘一眼就能看出来有哪些改动还悬而未决。在DXP Preferences偏好设置里找到Version Control节点是接入外部VCS的配置入口。选择VCS类型、指定可执行文件路径、启用版本控制都在这个位置完成。搞清楚了这几个入口的位置后面的配置流程就顺理成章了。3. 实测把AD项目接入Git的完整配置流程3.1 第一步装好Git并完成基础配置我以Git方案为主线来讲SVN的做法大同小异需要用到的SVN客户端另行准备即可。如果已经装了Git for Windows这一步可以直接跳过。Git for Windows安装时基本可以一路Next唯一要注意的是在安装过程中选择调整PATH环境变量的选项选择“Git from the command line and also from 3rd-party software”这样AD才能找到git.exe。装完之后打开命令行敲一下git --version确认能正常输出版本号。接下来为当前系统用户配置用户名和邮箱注意这不是仓库的账号而是提交记录上显示的署名信息建议用跟团队沟通一致的名字方便后期追溯。git config --global user.name YourName git config --global user.email youexample.com这一步很容易被忽略但不配置的话后续在AD里提交代码时Git会报错报错信息还容易让人一头雾水。曾经我在一台新电脑上折腾了半天提交失败最后查日志才发现就是没设置这两行。3.2 第二步让AD“看到”你的仓库AD本身不会帮你创建仓库它做的是把当前项目文件夹作为一个已完成初始化的Git工作副本连接起来。所以要先在项目文件夹里初始化仓库。假设你的工程文件在D:\Projects\STM32_DevKit在该目录下打开Git Bash运行git init这一步会在文件夹里生成一个.git目录这就是仓库本体。建议顺手创建并填写.gitignore文件把AD自动生成的输出、缓存目录排除在版本管理之外这部分后面专门展开讲。接下来打开Altium Designer进入DXP Preferences设置页面左侧面板选择Version Control节点。勾选Enable Version Control。VCS Type下拉框选择Git。在下面指定Git executable path指向Git安装目录下的git.exe路径通常是C:\Program Files\Git\bin\git.exe。点击Test按钮验证AD能不能正确调用Git。测试通过后切换到Projects面板右键点击你的工程文件.PrjPcb在Version Control子菜单里应该能看到Add to Version Control、Commit Whole Project等选项说明AD已经成功识别当前文件夹是一个Git仓库了。这里有一个容易踩的坑AD识别仓库的位置是“工程文件所在的项目文件夹”不是原理图所在的那个文件夹。如果发现右键后Version Control菜单是灰的多半是工程目录结构的问题把整个物理文件夹和.PrjPcb所在目录对齐即可。3.3 第三步首次提交把项目基线打上第一次提交是整个团队后续所有版本历史的起点也就是“基线”。在AD里操作很直观右键工程文件选择Version Control - Commit Whole Project。AD会弹出一个提交窗口列出此次将要提交的所有文件下方是提交信息输入框。输入一个能代表当前状态的提交说明建议按照“模块-改动内容-状态”的格式书写例如“Initial baseline for STM32 core board. Pre-layout schematic release.”中文写“初始基线STM32核心板原理图冻结PCB还未开始布局”也一样没有什么硬性规定关键是让人看得懂。点击OK后AD会调用Git完成这个提交。此时到Version Control面板刷新一下可以看到项目里所有文件的状态图标都变成了绿色的勾文件列表里出现对应的版本号和提交时间。第一次提交完成后最好做个验证随便改几个元件的位号或移动一下丝印保存文件再看Project面板对应文件应该立刻变成已修改的状态。确认这个反馈链条通了说明版本控制已经真正生效可以放心用了。3.4 日常循环Edit-Update-Commit的正确姿势版本控制接入以后日常操作其实就三个动作改文件、更新本地、提交改动。更新是什么意思呢在多人协作时别人可能已经提交了新版本你在本地打开旧文件继续改等提交时就会冲突。所以正确流程是动工之前先右键工程文件选择Version Control - Update从远程仓库拉取最新代码改完之后再Commit把改动推上去。这个“先拉后推”的习惯能省一大半冲突的痛苦。AD里的Update对应Git的pullCommit对应git commit另外还有一个Update Project from Version Control相当于对整个项目做一次完整同步。如果只改了某个原理图或PCB单独右键文件做Update或Commit效率更高。提交频率方面我的建议是“一个可验证的阶段提交一次”不要堆积十天半个月才提交一次也不要改一个电容标号就提交一版。比如“完成电源模块布局”“DRC清零”“导出Gerber前最终状态”这些都是合理的提交节点每个提交都是可独立查看和回溯的里程碑。4. 进阶玩法历史回滚、分支实验与团队协作4.1 用历史版本找回丢掉的“老方案”版本控制用得最多的功能之一就是对比历史版本、找回被淘汰的方案。在AD里右键某个文件选择Version Control - Show History会列出该文件的所有历史版本。点击任意一条历史记录可以看到提交时间、提交人、提交说明还能选择直接打开这个历史版本另存为副本或者与当前版本做对比。有一次我帮同事排查问题他说明明记得某个电阻之前是10k现在怎么变成4.7k了。打开这个原理图的历史记录对比两个月前的版本一眼看到有个人在某次提交说明里写了“调高LED亮度R5改4.7k”。如果不靠版本控制这种改动归因几乎只能靠人的记忆去猜而且大概率猜不准。AD还支持对两个版本进行差异对比。在工程文件或某个源文件上使用Compare功能原理图层面可以对比元件的添加/删除/属性变化PCB层面可以发现走线、铜区域或过孔位置的差异。这个能力在做版本评审、检查同事改动是否合理时非常实用。提醒一句历史对比发现要改回去时不要直接编辑过去的历史版本正确做法是基于当前最新版本修改或者使用Git的revert机制生成一个新的提交。硬去改历史会产生一堆分支烦恼没必要自找麻烦。4.2 分支做实验、改版不慌的底气分支在硬件设计中其实是一种非常优雅的“并行空间”。设想这样一个场景当前产品已经投产你要研究下一代布局调整比如改动DDR走线拓扑或调整电源平面分割但又不想污染稳定的主干版本。这时候从主干拉一个分支所有实验性的改动全部放在分支里不影响当前生产版本的整洁。在AD里操作分支没有图形化的一键按钮建议结合外部Git GUI工具比如SourceTree或GitHub Desktop来做分支切换和合并。AD只认当前工作区是什么状态所以只要外部工具切换了分支AD里打开的就是那个分支对应的文件内容。AD负责把“文件状态”展示清楚仓库级别的分支管理交给专门的Git工具更顺手。实验分支做好了想并回主干先把主干的更新内容合并到分支确认没有问题后再切回主干合并分支这属于常规Git操作。这里有几个具体的坑要提前讲清楚。因为原理图和PCB是二进制合并操作其实是很脆弱的合并时一旦同一个文件两边都有改动Git无法像代码那样自动合并只能选定一个版本覆盖。所以在硬件项目里分支实验的核心法则是同一时间图中和PCB只有一个分支在动等一个分支稳定了再改另一个分支并尽快合并回主干然后删除远分支。分支保存的是“一个完整版本的快照”而不是持续同时增删的活文档。4.3 团队协作的提交流程与提交规范多人协作使用AD加版本控制时最怕的不是技术问题而是流程混乱一个文件同时有几个人在改。先说流程建议。项目应设一名“集成负责人”通常由硬件组长或项目owner担任。他的职责是所有合并操作、发布版本的提交、分支的创建与清理。其他成员在各自的任务分支上工作完成后通知负责人合并。这样能在流程上减少两个人在同一份PCB上交叉覆盖的概率。如果团队习惯只在一条主干上协作那么至少约定“不在别人正在修改的页面上工作”动手之前同步一次远程最新状态明确改动范围提交前先Update提交信息写清楚改动目的。这几个习惯动作就能规避大部分协同问题。提交规范方面我的建议很简单必须包含“改了什么”和“为什么改”。很多工程师喜欢用“update”“modify”这种模糊词汇半年后看历史记录等于什么都没写。比如“修改DDR信号线等长规则解决SI仿真中setup timing margin不足问题”就比“更新DDR布线”有价值得多。一次提交对应一个逻辑改动不要把“改了原理图、又调了几处PCB丝印、顺手换了个三极管库”混在一起混合提交会让后期回滚变得很困难。远程仓库的承载方式没有唯一标准可以用公司内网的GitLab、Gitee私库乃至一台NAS上的裸仓库都可以。关键是权限控制做好成员能访问的项目范围不要太宽涉及硬件原理图这种核心资产的什么时候都加一道访问控制更放心。另外强烈建议提交之前先用AD的Project Releaser或者是在其他工程师那里过一遍DRC确认没有明显的连接性错误再提交。版本控制只解决管理问题不解决电路正确性问题如果提交上去的是一个有电气错误的版本历史记录记录的是错误的演进也没有太大帮助。5. 高频问题实录这些坑我都替你踩过了5.1 版本控制不生效、图标不出现的排查接入Git后最常见的问题就是Projects面板里完全不出现状态图标Version Control面板显示一堆错误信息或者是右键菜单的版本控制项灰掉。遇到这种情况按如下顺序排查基本能定位。第一确认Preferences里的VCS类型和git.exe路径正确点Test能通过。在装了多个Git客户端或某些软件内置了Git的机器上AD可能找到的不是同一个Git建议路径写绝对路径而不是依赖环境变量。第二确认当前打开的工程文件夹确实有.git目录。有的工程师在AD里打开了D盘一个工程却在E盘另一个文件夹里git init这当然找不到状态。这是“仓库根目录”与“工程目录”错位的问题。第三确认仓库没有被损坏命令行里执行git status看是否报错。有时候Windows的权限问题或者杀毒软件锁定.git文件夹会影响AD读取状态。重启AD再试大部分情况下能恢复。第四如果在AD中新增一个元件库或者原理图但状态并不变化检查一下这个文件是不是放在项目文件夹之外AD只对项目目录内的文件做版本监控外部文件不可能被纳入。5.2 二进制冲突硬件设计的经典难题原理图和PCB是二进制的这个特点决定了冲突解决方式跟代码完全不同。代码冲突可以打开文件看几行内容手动合并原理图文件冲突了没有任何工具能帮你做“取两者之长”的合并只能二选一。比如同事A和同事B同时克隆了最新版本A改了原理图第2页的电源部分B改了第5页的MCU部分先后都提交到远程后提交的一方一定会报冲突。遇到这种情况AD的界面提示往往不直观很多人第一次撞上会慌。实际上解决方案很简单确定以哪个版本为准用Git命令或者GUI工具做checkout强行用这个版本覆盖本地或合并。这意味着总会丢失一部分改动所以更好的策略是从源头避免只让一个人负责同一份原理图或PCB的维护其他人通过提需求的方式让他改而不是各拉各的版本自己动手。还有一个从SVN那边带过来的传统做法也可以借鉴在SVN里可以给文件设置“锁定”谁要改某个文件就先Lock改完提交再解锁。Git虽然不强制但团队完全可以把这当做人肉约定。我的团队就是约定谁要动PCB先在群里说一声“PCB我锁了状态改到X点”再开始动手实际这个流程自从执行之后二进制冲突出现次数几乎降为零。5.3 那些不该提交进仓库的文件夹很多人的Git仓库最后变成了一堆垃圾场原因就是什么文件都往上放。AD项目里常见的自动生成文件比如Outputs、History、__Previews等目录并不适合纳入版本管理。这些目录里是临时产生的预览、历史快照和生成文档每次打开工程都会变化放进仓库只会让每次提交都带着一堆无关改动也容易让仓库体积膨胀得非常快。我的建议是初始化仓库后立即创建.gitignore一个可用的参考模板如下# AD generated files History/ Outputs/ Project Logs/ __Previews/ Generated Files/ *.log *.bak Libraries integrated/Library folders can be ignored if they are not used # Windows temporary files Thumbs.db desktop.ini需要注意每台机器的工程输出目录名字可能与上面不同根据自己的目录结构调整。有一个比较稳妥的思路除了源工程文件.PrjPcb、.SchDoc、.PcbDoc、.PcbLib、.SchLib以及README等文档之外其他能重新生成的目录一律忽略。关于AD本地缓存和History的清理顺便多说一句AD本身的Local History是存放在项目文件夹下的History目录里的用久了会比较大。绝不建议去Git仓库中清理History目录后发现版本控制失效因为那个History和Git历史不是一回事。Git历史在.git目录里与AD的History无关。清理AD缓存可以从DXP Preferences里用Cleanup History功能做或者删掉History目录镜像的只是AD本地历史快照不影响Git。5.4 版本控制与AD本地缓存、History别混淆版本控制和AD本来就有两种历史体系。Version Control面板管的是Git或SVN记录AD会自动对本地文件做快照存在Local History里。这两个东西看着很像但边界很清晰。AD本地历史是纯单人防护的它的快照存取都在你本机磁盘上。如果你换了一台电脑或者把项目拷给别人本地历史并不会跟随你走。而版本控制的历史是跟随仓库的提交到远程之后谁clone下来都能看到全部历史记录。所以不要把这两者混为一谈AD本地缓存可以看作临时恢复的手段真正的项目记忆还是得靠版本控制来承载。另外AD的缓存文件偶尔也会引发一些诡异现象比如打开工程特别卡、文件列表异常甚至是修改后保存提示“文件被占用”。这种时候按官方方式清理提示缓存目录重建Local History一般就能解决。只要版本控制仓库状态是干净的清理本地缓存就不会影响工程源文件本身这也是版本控制给你兜底的另一种形式。结尾版本控制这件小事值得尽早安排上版本控制在硬件设计里的价值用过三个月之后会体会得越来越深。它不光是“防手滑删文件”这种被动防御更是一种正向的设计习惯逼着你在每个里程碑节点把状态固化下来逼着你在提交时把思路用语言整理一遍这个习惯本身就能减少大量低级返工。我现在每次动板子打开Project面板的第一件事就是看版本控制状态提交说明也写得尽量清楚宁可多写两个字也不要含糊。半年后回看当时的记录那些当时觉得“无关紧要”的备注往往成了定位问题最直接的线索。如果你还没给Altium Designer工程接入版本控制建议从今天这个项目开始花半小时把Git仓库初始化好、把第一次基线提交打上。你不需要成为Git专家日常就用AD界面里的update和commit两个操作已经能覆盖九成需求。等用顺了再慢慢探索分支、差异对比、远程协作这些晋升技能。画板子这件事电路上的坑已经够多了工程管理上的坑能少一个是一个。
