---

KiCad Plugin（KiCad 插件功能）正是 2026 年所有尋求自動化、高效開發的 PCB（印刷電路板）設計師的必修秘笈。透過 Python（高階程式語言）腳本自動化重複的設計、修改與重工，是硬體工程師釋放生產力的終極途徑。然而，當我們在開發自訂輔助插件時，卻經常會遇到代碼明明沒寫錯、軟體功能莫名失效，甚至找不到原因的崩潰時刻。

如果您在開發插件時，也曾遇到程式莫名其妙卡死、無法正常調用軟體功能，甚至面臨「明明已經移走檔案，重啟後插件卻依然頑固存在」的離奇現象，那這篇文章就是為您準備的！我們將用最簡單好懂的實戰步驟，帶您突破這些隱藏的路徑陷阱，讓您的自訂插件開發重新變得流暢又高效！

什麼是 KiCad Plugin？

簡單來說，KiCad Plugin（KiCad 插件功能）就是為了電路板設計師量身打造的「自動化外掛助手」。透過 KiCad 內置的 Python API（應用程式介面），我們可以把自己在設計 PCB（印刷電路板）時，那些需要反覆點擊滑鼠、手工調整走線、或是重複對齊元件的繁瑣重工，全部寫成一段自動化腳本，一秒鐘交給軟體自動執行。

學會開發自訂輔助插件，意味著你不再只是軟體的使用者，而是電路設計流程的「主宰者」。你可以將所有無意義的重複勞動一鍵化為無形，把珍貴的時間真正留給高價值的電路架構與硬體優化。但在進入這套極具魔力的開發流程前，我們首先要帶您了解自製插件能為電路設計帶來哪些驚人的自動化改變。

KiCad Plugin 可以做哪些事

在設計 PCB（印刷電路板）的實戰中，我們經常會遇到大量且無意義的重複勞動。透過 KiCad Plugin（KiCad 插件功能），您可以實現高度客製化的設計自動化：

• 自動化佈線與特定清理
  自動化清除指定範圍內的走線（例如我們本篇實戰中的「一鍵區域走線切除器」），或自動建立特定幾何形狀的網格與屏蔽走線。
• 批次元件佈局與精確對齊
  當需要排列大量矩形或圓形分佈的 LED（發光二極體）或測試點時，插件可以直接依據數學公式快速且精準地定位各個元件，完全免去手工逐一對齊的繁瑣。
• 設計規則檢查（DRC）的客製化擴充
  在官方內建的 DRC（設計規則檢查）之外，插件可以幫助您撰寫特殊的物理間距檢查、阻抗天線追蹤，或者是特定防呆規格的二次檢測。
• 自動生成與匯出生產資料
  包含一鍵生成並客製化排序的 BOM（物料清單）表、貼片機所需的座標位置檔，甚至是自動導出 STEP（三維圖形交換格式）的 3D 模型或生產用的 Gerber 製造檔案。

事前準備工作

在我們動手寫下第一行自動化代碼前，需要先備妥開發自訂插件所需的基礎執行環境與工具：

• 安裝官方最新版 KiCad 10.0
  本篇教學全面基於 KiCad 10.0（電路板設計軟體）最新穩定版。新版提供了更完善的 Python API（應用程式介面）綁定與 SWIG 穩定度。
• 準備優質的代碼編輯器
  強烈建議使用 VS Code（微軟程式碼編輯器）來開啟專案目錄，並安裝內建 of Python 擴充套件，這將提供絕佳的語法高亮與代碼自動完成提示。
• 啟動腳本控制台進行即時互動
  在 KiCad 的 PCB 編輯器中，點擊頂部選單的「系統 ➔ 腳本控制台」，即可彈出內置的互動式 Python shell（命令列直譯器）。在這裡輸入 import pcbnew 並嘗試調用簡單函數，是驗證 API 指令最安全且最快速的方法。

如何安裝插件

在 KiCad 中，手動開發的動作插件（Action Plugin）其檔案目錄結構必須極其規範。而在不同的作業系統中，`KiCad`（KiCad 電子設計自動化軟體）官方定義的載入路徑各不相同。理解這些路徑的差異，能讓我們徹底避免「插件放錯地方導致無法讀取」的窘境。

官方指定有效載入路徑
為了讓軟體啟動時能自動載入插件，我們必須將插件部署在官方所定義的有效目錄中：

• macOS（蘋果作業系統）★ 官方最推薦路徑：
  ~/Documents/KiCad/10.0/scripting/plugins/
  （此為不隱藏的個人文件夾目錄，最容易手動管理與清理，極力推薦！）
• macOS（蘋果作業系統）個人偏好設定路徑：
  ~/Library/Preferences/kicad/10.0/scripting/plugins/
  （此為個人設定檔隱藏資料夾，較不易查找，開發時不建議手動放入。）
• Windows（微軟作業系統）官方路徑：
  %APPDATA%\kicad\10.0\plugins\
• Linux（開源作業系統）官方路徑：
  ~/.local/share/kicad/10.0/plugins/

終極路徑除錯術

在 `macOS`（蘋果作業系統）下開發 `KiCad`（KiCad 電子設計自動化軟體）插件時，常會遇到「明明已經刪除/移走了檔案，但重新啟動軟體後，選單上的插件居然還存在，甚至運行舊版邏輯」的靈異現象。這通常是因為背景的記憶體未釋放（macOS 點擊紅色叉叉並未真正退出程式，需按 Cmd + Q 退出），或者是硬碟的某個隱藏角落還存有一份「分身實體檔案」。

以下分享兩招超強的 **「Python 控制台偵錯指令」**，教您直接透視 `KiCad` 記憶體，揪出它真正的藏身之處！

1. 印出您當前安裝的 KiCad 所有認可的搜尋路徑
在 PCB 編輯器中，打開「工具 ➔ 腳本控制台」，貼上以下單行指令並按下回車：

import pcbnew; print(pcbnew.PLUGIN_DIRECTORIES_SEARCH)

2. 終極偵探指令：從記憶體反查運行中插件的實體路徑
當您發現舊插件揮之不去時，貼上以下單行指令並按下回車，直接把這台電腦上正在運行的插件之**「真實硬碟絕對路徑」**秒速印出來！

import sys; print("\n".join([m.__file__ for m in sys.modules.values() if m and hasattr(m, "__file__") and m.__file__ and "trace" in m.__file__]))

插件程式碼

一鍵區域走線切除器實戰代碼

以下是完美融合上述安全機制、原生彈窗防護與精確列表移除邏輯的最終生產力代碼 (trace_cutter_action.py)：

import sys
import os
import traceback
# 💡 核心安全防護：防範 _pcbnew.so 共享庫 in macOS 進程中重複載入
if 'pcbnew' in sys.modules:
    pcbnew = sys.modules['pcbnew']
else:
    import pcbnew
try:
    import wx
except ImportError:
    wx = None
class TraceCutterPlugin(pcbnew.ActionPlugin):
    def defaults(self):
        self.name = "一鍵區域走線切除器"
        self.category = "佈線工具 (Routing Utilities)"
        self.description = "自動切除並清理指定區域內的所有 PCB 走線"
        self.show_toolbar_button = True
        try:
            self.icon_file_name = os.path.join(os.path.dirname(__file__), 'icon.png')
        except NameError:
            self.icon_file_name = ""
    def show_msg(self, message, is_error=False):
        """調用原生 wx 視窗彈出置頂提示"""
        if not wx:
            print(message)
            return
        parent = wx.GetActiveWindow()
        title = "❌ 走線切除器 - 錯誤" if is_error else "✂️ 一鍵區域走線切除器"
        style = wx.OK | (wx.ICON_ERROR if is_error else wx.ICON_INFORMATION)
        wx.MessageBox(message, title, style, parent)
    def Run(self):
        try:
            # 1. 獲取當前編輯器設計板
            board = pcbnew.GetBoard()
            if not board:
                self.show_msg("❌ 未能檢測到打開的 PCB 專案板！", is_error=True)
                return
            # 💡 SWIG 指針安全轉型：當物件退化為裸指針時的官方 Cast 強轉防護
            if not hasattr(board, 'GetLayerID'):
                try:
                    board = pcbnew.Cast_to_BOARD(board)
                except Exception as e:
                    self.show_msg(f"⚠️ [SWIG 轉型失敗] {e}", is_error=True)
            # 2. 獲取輔助繪圖圖層 User.Drawings
            target_layer = board.GetLayerID("User.Drawings")
            # 3. 掃描圖層上的繪圖框線
            drawings = board.GetDrawings()
            cutter_shapes = []
            for d in drawings:
                if d.GetLayer() == target_layer and hasattr(d, "GetBoundingBox"):
                    cutter_shapes.append(d)
            # 4. 若無繪圖框，給予清晰的視覺引導
            if not cutter_shapes:
                msg = (
                    "💡 未能在 'User.Drawings' 圖層上檢測到任何剪切框！\n\n"
                    "使用步驟：\n"
                    "1. 請在右側圖層管理器選擇「User.Drawings」圖層。\n"
                    "2. 使用畫圖工具（如矩形、圓形）在您想要清空的走線區域畫一個臨時框線。\n"
                    "3. 點擊本按鈕，它就會自動把框內的所有走線清空並抹除框線！"
                )
                self.show_msg(msg)
                return
            # 5. 開始安全移除走線
            tracks = board.GetTracks()
            deleted_count = 0
            for shape in cutter_shapes:
                bbox = shape.GetBoundingBox()
                left = bbox.GetLeft()
                right = bbox.GetRight()
                top = min(bbox.GetTop(), bbox.GetBottom())
                bottom = max(bbox.GetTop(), bbox.GetBottom())
                # 複製列表以防在遍歷時修改發生索引遺漏
                for track in list(tracks): 
                    start_pt = track.GetStart()
                    end_pt = track.GetEnd()
                    # 判斷端點是否在剪刀框內部
                    start_inside = (left <= start_pt.x <= right) and (top <= start_pt.y <= bottom)
                    end_inside = (left <= end_pt.x <= right) and (top <= end_pt.y <= bottom)
                    if start_inside or end_inside:
                        board.Remove(track)
                        deleted_count += 1
                        if track in tracks:
                            tracks.remove(track) # 採用正確的 Python 列表移除方法
                # 自動擦除繪圖框，保持 PCB 整潔無痕
                board.Remove(shape)
            # 6. 強制重新繪製畫面
            pcbnew.Refresh()
            
            self.show_msg(
                f"✅ 走線清空成功！\n\n"
                f"• 共清空了 {deleted_count} 條剪刀框內的走線！\n"
                f"• {len(cutter_shapes)} 個臨時剪切框已自動擦除無痕！\n"
                f"• PCB 編輯器畫面已重新整理！"
            )
        except Exception as e:
            err_msg = f"❌ 插件執行時發生錯誤！\n\n型別：{type(e).__name__}\n內容：{str(e)}\n\n詳細追蹤資訊：\n{traceback.format_exc()}"
            self.show_msg(err_msg, is_error=True)
# 只有當作為外部插件被 KiCad 正常載入時才向系統註冊
if __name__ != '__main__':
    TraceCutterPlugin().register()

快速部署與測試

當您將上述程式碼複製完成後，請跟著以下簡單的步驟，一步一步將它安裝進您的 KiCad（KiCad 電子設計自動化軟體）中：

• 儲存檔案：將上方的 Python（高階程式語言）程式碼，在您的編輯器中另存新檔，檔案名稱命名為 trace_cutter_action.py。
• 移至官方載入路徑：將此 trace_cutter_action.py 檔案移動或複製到我們前面提到的官方最推薦路徑中：
  • macOS（蘋果作業系統）：~/Documents/KiCad/10.0/scripting/plugins/
  • Windows（微軟作業系統）：%APPDATA%\kicad\10.0\plugins\
• 開啟 PCB 編輯器：啟動 KiCad，並進入您要調試的 PCB Editor（印刷電路板編輯器）。
• 重新整理並運行：在上方選單點選 Tools（工具） ➔ External Plugins（外部插件） ➔ Refresh Plugins（重新整理插件）。此時，我們的「一鍵區域走線切除器」就會帥氣地出現在選單列表中，點擊即可開始一鍵自動化測試！

結論

KiCad Plugin（KiCad 插件功能）在硬體與軟體協同開發的時代，是決定工程師研發速度的分水嶺。掌握這項高階工具的自動化能力，能讓我們一秒擺脫手工修改電路板的繁瑣。透過本篇介紹的自動化插件開發，我們不僅成功學會了如何從零建構一個實用的「一鍵區域走線切除器」，更理解了如何正確地在不同平台部署與安裝插件，甚至掌握了進階的 Python 記憶體反查與路徑除錯術，為我們的日常設計建立起高效的生產力工作流。

下次在為您的 PCB（印刷電路板）設計新功能時，不妨先開啟自訂的插件架構。當您從「反覆手工拉線」中解放，開始專注於系統的優化與設計架構的維護時，您就已經跨入了全新層次的高效開發境界。

---