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 以外的版本，需要另行評估適用範圍。