做PCB这行久了你会越来越觉得BOM这东西做得好不好直接决定贴片厂对你的态度。以前我导出的BOM要么是Excel、要么是PDF一大串位号、封装、料号堆在一起工人得对着板子上的丝印一个个找找错了就焊错焊错了就报废。直到我在GitHub上接触到交互式BOM插件第一次生成HTML版的交互式BOM时那种“终于能指着板子说话了”的感觉确实是传统BOM给不了的。它把物料清单和PCB图形放在同一个页面里点击任意一个位号板子上对应的元件直接高亮特别适合贴片、维修、返修定位。但说实话从GitHub下载插件到把它跑在Altium Designer以下简称AD里中间全是坑下回来的文件不知道装哪个、AD版本一变脚本就报错、网上教程又不全。这篇文章我把自己折腾过的完整路径捋一遍从GitHub选文件、AD安装到版本兼容性排查每一步说清楚希望能帮你少走弯路。1. 交互式BOM插件到底是什么解决什么问题1.1 传统BOM为什么让人头疼先说说我之前的实际经历。用AD自带功能导出BOM操作本身不算难打开PCB文件后在File菜单里找到Assembly Outputs里的Bill of Materials选择导出Excel或者PDF就行。可问题在于导出来的东西本质还是“一张脱离板子的表格”。工厂那边拿到BOM后要人工比对位号在板子上的实际位置。一旦板子上元件稍微密集一点或者位号丝印被遮挡找起来就非常痛苦。尤其碰上同封装、不同阻值的电阻电容光靠文字描述特别容易贴错。我自己就吃过亏有次试产10片板子因为某个电容位号看错整批全部返工从那以后我就在想BOM能不能做得更直观一些。另外还有个场景很常见板子焊接完发现问题需要返修某个元件。传统做法是把PDF里的位号复制到AD里搜索再跳转到PCB对应区域来回切窗口、翻图层效率低到让人抓狂。交互式BOM的出现基本把这几个痛点一次性解决了。1.2 交互式BOM的能力清单交互式BOM插件生成的HTML文件本质是一个自包含的网页不需要安装任何额外软件浏览器打开就能用。它把PCB板图和BOM表格放在同一个页面里左右分栏实现了几个非常实用的能力点击左侧BOM里的任意一行右侧PCB图形中对应的元件位置就会高亮并自动缩放居中。点击右侧PCB图形上的某个元件左侧BOM列表也会自动滚动到对应条目。支持按封装、位号、Value值筛选和分组几百个元件也能快速过滤。支持给指定元件打上DNP标记也就是“不贴装”标记小批量试产或兼容多BOM方案时特别实用。板图支持缩放、平移元件坐标、旋转角度、所在层等信息都能直接展示。HTML文件是单文件结构没有外部依赖拷给贴片厂、发到工作群、放进项目归档任何电脑上双击都能打开。1.3 它是怎么实现的一句话讲透原理理解了原理后面排错会轻松很多。交互式BOM插件做的事情并不神秘它通过AD的脚本接口遍历当前PCB文件里所有元件把位号、封装、坐标、旋转角度、所在层这些信息读取出来再结合板框数据生成一份JavaScript数据文件最后用一套HTML模板把数据渲染成可视化页面。所以这个插件本质上就是一个数据提取器加渲染器。它依赖AD打开PCB文件但并不依赖你电脑上是否安装了AD因为生成的是完全独立的HTML。这个特性在后面讲版本兼容性的时候非常关键我建议你先记住这一点插件在AD里的作用是“读取并导出”真正给你看板子的是浏览器。2. 从GitHub下载插件选对文件、避开封装陷阱2.1 怎么找到靠谱的仓库GitHub上交互式BOM相关的项目其实不止一个搜索关键词无非就是Interactive BOM、InteractiveHtmlBom、Altium BOM这几个方向。我的建议是优先看star数高、更新日期靠前的仓库尤其要看README里是否明确写了支持Altium Designer。这里必须提醒一下有些项目是专门为KiCad设计的虽然同样叫交互式BOM但和AD不直接兼容。下载之前最好先扫一眼仓库的文档看看是否提供了AD脚本源码或者是否说明了从AD导出的流程。我最初就下错过一个KiCad专用版本研究半天才发现根本不适用。判断仓库是否靠谱我一般看三点README里的使用说明是否详细、最近提交时间是否超过一年、Issues里有没有人反馈AD版本相关的问题。如果一个项目很久没更新但还在被大量人下载说明它大概率已经稳定了如果连README都写不清楚那就算能用后续出问题你也没地方查。2.2 Release包还是源码包别下错文件进入仓库后很多人的第一反应是直接点绿色的Code按钮下载ZIP。这个操作本身没错但如果项目有Release版本我会更推荐你从Release页面下载。Release页面通常提供的是整理好的发布包有的还会附带编译好的脚本工程、示例文件、使用文档比你直接打包下载整个源码库更干净。更重要的是Release页面的版本号清晰方便你记录当前用的是哪个版本后面排查问题时能准确说出“我下的是v1.2.3”。如果项目没有Release那就只能下载Source code压缩包了。这种情况要留意压缩包解压后的目录结构有些源码包里有多个版本的脚本文件夹比如Altium目录下按AD版本分了文件夹你要选对对应版本再使用而不是把整个包一股脑塞给AD。还有一个容易忽略的细节很多浏览器自带解压功能下载后的ZIP文件被系统默认“直接打开”成虚拟文件夹。如果你把这种虚拟文件夹里的脚本工程直接用AD打开路径会有问题容易导致运行脚本时找不到依赖文件。正确做法是右键ZIP文件选择“全部解压”放到一个固定目录里再用。2.3 下载过程中常见的网络与文件问题GitHub在国内访问时快时慢这个是现实问题。页面打不开、下载中断、Release附件半天不跳转我都碰到过。这种时候我不太建议死磕同一个网络环境下反复重试可以把网络从办公室切换到手机热点试一次或者换个时段再下很多时候就是节点抖动过一会儿自己就好了。如果实在下载不动还有几个合规且有效的路子一是去国内代码托管平台搜索同名仓库很多热门开源项目都有人做每日同步从那边拉一般会稳定很多二是直接在行业交流群问一句“谁有交互式BOM脚本包”大概率能遇到热心人分享拿到后自己再核对一下版本号三是让公司有冗余网络环境的同事代下载后传到共享盘。文件下载完成后建议第一时间看一眼压缩包里的README和版本说明确认你拿到的不是几年前的远古版本。如果下载来源是第三方同步仓库最好再和GitHub原仓库的最新版本比一下避免拿到一个被改过的中间版本后面出了问题都不知道该去哪个Issues里找答案。2.4 下载后先做三件事这是我个人总结的固定动作能帮你避免很多低级问题。第一查版本。打开Release页面或者源码包里的版本文件把这个版本号记录下来。后面如果遇到兼容性问题去GitHub Issues里搜直接用“AD 23”“Altium 23”加版本号组合搜定位会非常准。第二看README里的环境要求。有些插件明确写了“Tested with Altium Designer 17/20/21”说明作者是在这几个版本上验证过的。如果你的AD版本不在列表里不代表不能用但你要有心理准备可能需要自己动手做适配。第三核对文件结构。打开解压后的目录确认里面是否包含.PrjScr脚本工程文件还是只有.PAS源文件。这个区别会直接影响你在AD里怎么加载它下面第三部分会细说。3. 在Altium Designer中正确安装与启动插件3.1 不同AD版本下运行脚本的入口很多人卡在第一步不是插件的问题而是根本找不到AD的运行脚本入口。AD这些年界面的变化比较大不同大版本入口位置不太一样但整体逻辑是通的。老版本的AD比如AD15、16、17菜单栏上有个DXP菜单里面直接有Run Script选项。从AD18开始DXP菜单被取消了运行脚本的入口被挪到了菜单栏的File下或者需要通过右上角的菜单进入。再新一点的版本界面更扁平化各种命令要用右上角的搜索框来定位。我的办法很简单别死记入口位置在AD的搜索框里输入“Script”或“Run Script”一般都能把对应命令搜出来。如果实在找不到还有一个通用做法打开任意一个PCB文件后按F11调出View面板不行我这里不瞎说。最保险的还是看AD的帮助文档或者直接看脚本项目README里作者贴的截图按图索骥。3.2 脚本工程与脚本文件的区别下载解压后你可能会看到两类文件一类是单独的.PAS或.JS文件这类文件可以直接运行另一类是.PrjScr脚本工程文件里面可能包含多个脚本文件和配置。如果是脚本工程我建议你在AD里用File Open的方式直接打开这个.PrjScr文件打开后会在Projects面板里看到这个脚本工程。这样做的最大好处是脚本涉及多个文件依赖时AD能正确关联起来不会出现“运行一半找不到子函数”的报错。如果是单独的脚本文件直接用Run Script命令在弹出的对话框里找到那个.PAS文件即可。首次运行需要手动定位文件但AD会记住历史记录下次再从Run Script的最近列表里选就行。这里有个个人建议不管你是那种文件都别把脚本放在U盘或者桌面这种不稳定的位置。我自己习惯在D盘建一个专门的AD_Scripts目录按工具名称建子文件夹解压后的脚本统一放进去。这样既方便AD记住固定路径也方便升级备份。3.3 把脚本固定下来工具栏按钮与快捷键设置每次都要通过Run Script再翻历史列表用久了还是觉得麻烦。我给自己的AD配了快捷键和工具栏按钮用起来就顺手多了。具体做法是这样在AD的菜单栏或工具栏空白处点右键选择Customize打开自定义对话框。在Commands标签页里找到Scripts分类里面会列出已经加载过的脚本命令。把这个命令直接拖拽到顶部工具栏上就会生成一个按钮。之后再右键这个按钮选择Edit就能分配一个快捷键比如我习惯用CtrlAltB来跑交互式BOM。设置完成后运行插件就变成了一键操作。对于每天要出好几次BOM的人来说这个配置能省下大量重复操作值得花两分钟设置一下。3.4 第一次运行前必须确认的三件事第一当前必须打开着一个PCB文件。交互式BOM脚本的原理就是从当前PCB读取元件数据如果你在原理图界面或者没有打开任何文件的时候运行弹出的只会是错误提示。第二输出路径建议用纯英文目录。不要小看这个问题AD脚本对中文路径的处理一直不太友好生成HTML时如果路径里有中文或特殊字符轻则保存失败重则生成的文件打开后不正常。我统一用D:\BOM_Output这样的固定目录省心很多。第三PCB文件名尽量也保持英文。有些项目文件保存成中文名脚本在读取和拼接输出文件时也会出现莫名其妙的异常。因为这个原因连累HTML生成失败实在不划算。4. AD版本兼容性问题全解析4.1 AD版本演化了什么脚本引擎与API在变AD从Protel时代一路走过来脚本引擎和API层面一直在变。很多交互式BOM脚本是几年前写的现在拿到最新版AD上跑很容易出现各种兼容性问题。老版本AD里比如AD17之前脚本环境和DXP深度绑定很多系统函数调用路径和现在不一样。AD18之后进行了大规模UI重构菜单结构、工具栏都变了但底层脚本引擎其实还保留着。到了AD20以后PCB对象模型持续更新坐标计算、单位换算、图层处理这些都在变。最直观的感受就是同一个脚本在AD17上运行正常换到AD21上可能直接报“Undeclared identifier”或者运行时异常。而且不同大版本对坐标的内部表示方式也有区别AD内部坐标不是直接用mil或者mm而是用系统坐标单位脚本里一旦用错了换算函数读取出来的元件坐标要么全部为0要么整体偏移生成出来的HTML自然也不对。4.2 典型兼容性报错对照表我把这些年遇到过的、网上群里反馈过的一些典型报错整理成了下面这张速查表不一定覆盖全部情况但能给你排错提供一个方向报错现象可能原因解决思路Undeclared identifier脚本里用了当前AD版本不认识的函数或类型打开报错行去官方API文档查替代函数Invalid floating point operation坐标或数值转换异常常见于单位换算检查脚本里的单位换算统一到AD当前版本规则Project not found脚本工程没正确加载用File Open打开对应的.PrjScr文件Debugger exception脚本运行中API调用失败用断点调试定位到Issues里搜AD版本关键词生成的HTML里坐标为0坐标读取或单位转换出错检查PCB文件是否正常打开、单位设置是否统一HTML有BOM但板图为空白板框数据读取失败检查PCB的板框是否在机械层1、是否闭合4.3 作者不维护了怎么办自己改代码的几条路子开源插件最怕的就是作者弃坑。项目两三年没更新AD却在一年一个大版本地往前走迟早有一天会跑不起来。遇到这种情况我的处理顺序是这样的先去GitHub Issues里搜一圈输入你的AD版本号看看有没有人已经报了同样的问题。很多项目即使作者不更新了社区里也会有人提交修复分支甚至提出Pull Request你可以直接下载那个修复后的版本。如果没人修那就只能自己动手。AD的脚本调试功能是可以用的在Run Script时选择Debug模式逐行执行看具体报错在哪一行。结合AD官方脚本API文档查一下当前版本对应的方法和属性名称通常能修好60%的版本不兼容问题。这里分享一个思路老脚本用到的很多系统级API在新版本里未必被删掉了更多的只是路径变了或者名称变了。比如早期的坐标系转换函数在新版本API文档里可能被挪到了另一个单元下但底层实现逻辑没有本质变化。你只需要在代码里找到那一行把调用方式改成新版本对应的写法即可。4.4 绕开脚本引擎用独立工具生成交互式BOM如果你和我一样是个连Pascal都不太熟的人自己改脚本效率太低那还有一个更省心的方案绕开AD的脚本引擎用独立的交互式BOM工具。这类工具的原理是先利用AD自身功能导出BOM和坐标文件然后用Python等语言写的独立程序把两个文件合并处理生成交互式HTML。因为整个过程完全不依赖AD脚本环境所以AD版本怎么升级工具的兼容性都不会受影响。你只需要保证AD能正常导出所需的中间文件即可。这个方案的缺点是不能在AD里直接调用需要额外的几步导出操作流程上比脚本方案繁琐一些。但它的兼容性优势是实打实的尤其适合公司里AD版本不统一、有人用AD17有人用AD23这种场景。我觉得这两个思路不冲突AD脚本方案适合个人日常快速出图独立工具方案适合做团队统一流程。5. 核心实操与典型报错排查实录5.1 一次完整的交互式BOM生成过程为了让你对整个过程有个完整的画面感我用自己的实际项目走一遍流程。我的环境是AD20Windows 10从GitHub下载的交互式BOM脚本放在D:\AD_Scripts\InteractiveBOM目录下。操作步骤很简单打开PCB文件后通过快捷键CtrlAltB调起脚本在弹出的对话框里选择输出目录D:\BOM_Output等待状态栏提示完成。脚本执行的核心逻辑并不复杂大致是在AD内部遍历所有元件读取位置信息然后输出到临时数据文件。我这里用简化代码演示一下关键部分// DelphiScript 示意代码仅展示核心流程 procedure RunInteractiveBom; var Board : IPCB_Board; Iterator : IPCB_Iterator; Comp : IPCB_Component; OutFile : TextFile; begin Board : PCBServer.GetCurrentPCBBoard; if Board nil then begin ShowMessage(请先打开PCB文件再运行脚本); Exit; end; Iterator : Board.BoardIterator_Create; Iterator.AddFilter_ObjectSet(MkSet(eComponentObject)); Iterator.AddFilter_LayerSet(AllLayers); Iterator.AddFilter_Method(eProcessAll); AssignFile(OutFile, D:\BOM_Output\bom_data.txt); Rewrite(OutFile); Comp : Iterator.FirstPCBObject; while Comp nil do begin // 实际使用中这里要做坐标单位换算 Writeln(OutFile, Comp.SourceDesignator , Comp.Pattern , IntToStr(Comp.XLocation) , IntToStr(Comp.YLocation)); Comp : Iterator.NextPCBObject; end; Board.BoardIterator_Destroy(Iterator); CloseFile(OutFile); ShowMessage(数据导出完成); end;这里特别说明一点示例代码中的坐标是AD内部坐标值实际脚本里需要根据插件要求转换成可读的mil或mm数据。不同AD版本提供的转换函数有所不同你的任务就是确保转换正确否则生成的HTML里元件位置会乱掉。5.2 HTML打开后常见的显示问题脚本运行成功、HTML也生成了但用浏览器打开后可能遇到各种显示问题这部分我踩过的坑很多。最常见的是双击HTML文件后默认用系统自带浏览器打开结果页面排版乱了或者点击高亮无反应。尤其某些老电脑上默认的IE浏览器对现代JavaScript支持不完整交互式BOM这种重度交互页面很容易出问题。解决办法很直接右键文件选择用Chrome或Edge打开并且把HTML文件设置为浏览器默认打开方式。还有一次我生成的HTML发到群里同事反馈打不开后来发现是因为他把文件重命名成了中文名而且夹在微信的缓存目录里。虽然HTML是自包含单文件理论上改名不影响内容但文件名里的全角字符加诡异路径还是可能引起浏览器展示异常。发给别人的文件文件名尽量保持简单比如BOM_v1.2.html这种格式。5.3 元件缺失、坐标错乱、板框显示异常怎么办如果HTML打开后BOM列表里缺了某些元件先回到AD里确认这些元件是否真的在PCB上。有些设计里会有未放置的元件或者元件在机械层被隐藏了脚本可能读不到。还有一种情况是元件没有位号脚本里做了过滤规则跳过了无位号元件。这种时候去PCB面板里检查一下Designator列是否为空。坐标错乱的问题我之前遇到过一回生成出来的元件位置整体偏移了几毫米看起来像整个板子被平移了。排查后发现是脚本里坐标原点和单位换算没对准再加上PCB文件里用了非标准的原点设置。解决方法是把PCB原点重置到标准位置或者修改脚本里的坐标补偿。板框显示异常最常见的原因是板框不在机械层1而是被画在了其他机械层。交互式BOM脚本默认读机械层1的板框数据你的板框在其他层时需要在脚本配置里指定层或者在AD里把板框复制到机械层1。另外板框线必须是闭合的如果有缺口渲染出来的板边线会连接不对看起来像缺了一块。5.4 大板卡顿与性能优化处理大型复杂板卡比如BGA密集的服务器主板、几百上千个元件的板子生成HTML后浏览器打开可能会卡顿甚至无响应。我的优化建议是这样的生成时尽量关闭一些高消耗选项比如不输出3D模型数据、不生成高分辨率丝印预渲染。如果插件支持可以在脚本配置里降低图形渲染精度。第二用Chrome或Edge打开后不要缩放得太小越小的缩放级别浏览器需要渲染的细节越多反而容易卡。第三如果HTML文件体积已经超过十几MB优先考虑减少输出内容而不是单纯升级电脑配置。可以说大多数卡顿问题不是电脑不行而是输出的HTML包含了过多的冗余数据。整理一下短板和非必需显示项效果立竿见影。6. 把交互式BOM用成日常流程6.1 我最推荐的BOM管理流程交互式BOM用顺手以后我现在每个项目的BOM管理流程基本固定了分享出来供你参考。板子原理图改完、PCB定稿打样之前我在AD里操作几步导出传统Excel BOM用于采购和归档再用交互式BOM脚本生成一份HTML用于装配和返修参考。这两份文件放在同一个项目文件夹里命名规范统一加日期和版本号比如Project_BOM_20250115_v1.3.xlsx和Project_BOM_20250115_v1.3.html。发到贴片厂前我会把HTML BOM和PCB的Gerber文件一起打包跟对接人强调一句“焊接的时候对着HTML点一下就知道元件在哪了”。实际反馈很好特别是首次试产的板子工厂能大幅减少找位号的时间错贴的概率也低了很多。返修场景更是离不开它。产品卖出去一段时间客户反馈某个功能不良我第一件事就是打开对应版本的HTML BOM点几下就能定位到嫌疑元件再配合原理图分析原因效率比以往翻了一倍不止。6.2 多人协作时的插件版本统一如果你在团队里插件版本统一这个问题一定要重视。我自己见过一个项目组有的人用AD17有的人用AD20从GitHub下载的插件脚本版本也不一致最后生成的HTML表单格式都不一样给客户交付时看起来很不规范。我的建议是团队内部指定一个“已验证可用”的插件版本把脚本目录和一份简单的使用说明放到内部共享盘或者版本管理系统里。新同事加入时直接从这个统一入口下载配置不要各自去GitHub海捞。这样既能避免版本混乱也能在GitHub临时不可用时保证项目不受影响。共享盘里的使用说明不用写得很长几句话讲清楚脚本放在哪个目录、AD里怎么加载、输出目录设置成什么、遇到报错先找谁。这就够了。6.3 升级AD前先想清楚这三件事很多人喜欢在新AD版本发布后就立刻升级但如果你重度依赖交互式BOM这类第三方脚本升级前一定要想清楚三件事。第一当前使用的脚本版本是否兼容新AD。不确定的话先看GitHub仓库有没有针对新版AD的更新说明或Issues反馈。第二旧版本AD还能不能用。公司如果有严格的版本管理升级前先确认旧版本的计划保留时间别急着卸载。第三新AD环境下是否已经完成了插件验证。我建议先在虚拟机或备用电脑上装上试用把BOM跑一遍确认无误再正式切到主力工作机。我个人在升级AD后踩过一次脚本兼容性的坑当时急着赶项目新AD装上就跑结果交互式BOM脚本直接报错临时又切回旧版AD才完成任务。从那以后我再也不轻易在项目进行到一半的时候升级AD了。宁可晚一点用上新功能也不能让日常流程卡壳。最后再分享一个小经验吧。交互式BOM插件这东西第一次用觉得新鲜用久了真的会成为习惯就像我每次PCB定稿后不生成一份HTML心里总觉得少了点什么。很多人觉得它只是个锦上添花的辅助工具但真正被它救过急的人才懂什么叫“一页纸说清楚板子上所有事”。如果你刚开始尝试建议从一个小项目开始跑通流程把脚本、快捷键、输出规范都理顺后面就全是收益了。