Qt Creator「無法解析的外部符號」錯誤：原因與解決步驟

錯誤現象

編譯提示「無法解析的外部符號」，且提示找不到某 obj 文件，但該文件確實存在於 debug 目錄下。

常見原因排查清單

1. 文件未參與編譯：.cpp 文件未添加到 .pro 的 SOURCES 變量中
2. 對象文件損壞/過期：執行「清理」後重新構建
3. 函數聲明與定義不匹配：參數類型、const 屬性、命名空間差異
4. 內聯函數定義在 .cpp 中：需移至頭文件或標記 inline
5. 模板函數定義在 .cpp 中：模板必須在頭文件完整實現
6. 靜態庫鏈接順序錯誤：依賴庫應放在被依賴庫之後

標準解決流程

# 1. 檢查 .pro 文件
SOURCES += main.cpp \
           myclass.cpp \  # 確保所有 .cpp 都在這裡
           utils.cpp

HEADERS += myclass.h \
           utils.h

# 2. 執行清理構建
# Qt Creator 菜單：構建 → 清理全部
# 或命令行：
make clean
qmake
make

進階排查技巧

• 查看編譯輸出日志，確認報錯符號具體來自哪個 .cpp
• 用 nm (Linux) 或 dumpbin /symbols (Windows) 檢查 .obj 導出符號
• 啟用「詳細輸出」選項獲取更多鏈接器信息

經驗總結

90% 情況下是「文件未加入 SOURCES」或「清理重構建」即可解決。養成修改 .pro 後執行 qmake 的習慣。