KiCad 迁移后找不到 3D 模型？只改出错的部分

1. 复制设计并明确检查范围

关闭 KiCad，复制项目、自定义封装库和模型文件夹。此时保持原文件夹完整不动。记录 KiCad 版本、操作系统、新旧根目录、项目位置、相关路径变量的值，以及是否有其他项目共用同一批模型。

列出准备检查的项目副本和库副本文件夹。同时纳入库中的 .kicad_mod 文件，以及包含已放置封装的 .kicad_pcb 文件。对受影响的元件，记录板上参考标号、库封装和预期应有的模型实体。这能为后续检查明确目标，避免假定每个封装都应该配有模型。

2. 建立范围明确的候选项清单

在 POSIX shell 中，从同时存放这两份副本的工作文件夹运行以下命令。把占位用的目录名替换为实际名称，并选择尚未使用的报告文件名。命令读取选定的设计文件，并把报告写到扫描文件夹之外。

rg --no-config --hidden --no-ignore --json --multiline --glob '*.kicad_mod' --glob '*.kicad_pcb' '\(model\s+"' -- ./project-copy ./library-copy > ../kicad-model-matches.jsonl 2> ../kicad-model-scan-errors.txt

读取 JSON 匹配记录及其 path、line_number、lines 和 submatches 字段；同一条记录可能包含多个匹配词元。打开每个候选文件，查看完整的模型引用。JSON 会保留文件名边界，包括文件名中的换行符；不要按冒号拆分这些记录。这是一项文本检索，不是 KiCad 解析器，也不是模型路径解析器。

扫描包含隐藏文件夹以及被忽略的文件夹，该模式可以找到位于行内或跨行的 model 词元。不跟随目录符号链接；二进制文件、归档文件和其他扩展名的文件不在声明的覆盖范围内。请明确加入其他需要检查的库副本根目录，并查看扫描错误。退出码 0 表示有匹配，1 表示无匹配，2 表示出错；任何一种都不能证明覆盖完整。使用 ripgrep 15.2.0 的一次有限范围 Linux 测试找到了预期的合成候选项，且输入文件的哈希未改变。本文未执行 KiCad GUI 操作、保存后重开，或 STEP 导出。

3. 为每个引用选择处理方式

共享的自定义变量：如果 ${MY_3DMODELS}/Connectors/part.step 中根目录之后的路径部分仍然正确，就检查新根目录下的该文件。若这样已足够，只需在 Preferences → Configure Paths 中更改 MY_3DMODELS。为新的共享根目录使用一个不重名的变量名，并直接用绝对文件夹路径作为变量值。外部定义的变量优先，且在这里显示为只读；应修改它的实际定义来源。KIPRJMOD 是例外，见下文。

项目相对引用：保留正常工作的 ${KIPRJMOD}/models/part.step 引用，并连同 models 目录一起移动项目。KIPRJMOD 随项目文件夹而定，不能被覆盖。对于直接使用 ../ 的路径，需要在受影响的视图中核实其实际解析上下文；只有现有相对引用不适用时，才选择明确的项目根目录或共享根目录。

旧版变量或嵌入文件：不要机械地把 KICAD6 替换成 KICAD10。先检查已显式设置的旧变量值、文档说明的回退规则和实际目标文件。保留正常工作的引用。同样，保留有效的 kicad-embed:// 引用，并在拥有该引用的电路板或封装中检查对应的嵌入文件条目；它不属于外部根目录替换的范围。

无法解析的外部路径或缺失的模型文件：记录预期文件及所需的最小编辑。新的根目录不能生成缺失的模型，也不能把 .wrl 引用变成一个实际可用的 .step 文件。选择替代文件前，确认真实文件名、扩展名和所需的导出格式。为每个受影响的引用保留清单中的处理决定：只改配置、保留不动、编辑，或待解决的文件缺失。

4. 只编辑确实需要修改的引用

对于已确认有误的外部路径，修改设计副本中选定的模型条目，或对严格限定范围的文本修改进行复核。只在已核实根目录下对应路径映射的位置替换旧根目录。除非另有明确的修正目的，否则保留文件名、扩展名、偏移、缩放和旋转；检查完整差异，查看是否存在无关变更或语法损坏。

检查对应的库封装和每个受影响的板上实例。KiCad 的 Compare Footprint with Library 工具可显示二者的差异。Update Footprints from Library 是范围更广的同步操作，可能更改定制过的板上封装；只有这些变化符合你的意图时才使用。路径修复不应悄悄替换自定义焊盘、图形或其他设计属性。

5. 重启并检查三项输出

更改路径配置后，退出并重启 KiCad。在封装编辑器的完整 3D 查看器（Footprint Editor 3D Viewer）中打开每个受影响的库封装，通常使用 Alt+3。Footprint Properties 中的小预览有助于编辑，但不能替代这项完整视图检查。然后在 PCB 3D 查看器（PCB 3D Viewer）中打开电路板副本，对照清单检查受影响的放置实例、朝向和模型实体。

启用元件导出，并按预期设置要导出的元件选择与排除条件，再把电路板副本导出为 STEP。VRML .wrl 模型不会直接包含在 STEP 输出中；启用 Substitute similarly named models 后，导出器可使用名称符合要求的 STEP 对应文件。应确认所需对应文件确实存在，不能仅凭可见的 VRML 预览就认为已经具备导出条件。

在将要接收该文件的机械 CAD 工具中打开导出的 STEP，对照预期检查实体和位置。记录哪些封装视图、电路板视图和导出检查已通过。有人报告某个查看器存在相对路径问题，这说明需要单独检查该查看器，并不证明所有安装环境都有相同缺陷。

6. 确认不再依赖旧根目录

在设计副本通过检查后，让旧的外部模型文件夹暂时无法被本次测试访问。只有不会干扰其他项目时，才采用可撤销的重命名；否则使用隔离的测试环境。退出 KiCad，重新打开项目副本，再次进行候选项扫描，并重新完成三项输出检查。对照所选目录布局审查剩余引用；有效的旧有引用、项目相对引用或嵌入引用，不会仅仅因为仍然存在就成为错误。

若模型消失、文件无法打开，或差异超出预期的改动范围，就恢复旧位置，并在继续之前解决该条目。将原始备份保留到下一次设计审查结束。后续更换机器、库或 KiCad 版本后，应再次执行相应检查。由插件管理的资源、不同的软件包目录布局，以及 KiCad 9–10 以外的版本，需要另行评估适用范围。