macOS下编译链接QtCore出现source file is not valid UTF-8错误

报错根因 #

该错误是macOS Framework目录结构和头文件搜索路径顺序不匹配导致的：
macOS下QtCore.framework是框架目录，根目录下的QtCore是二进制可执行库文件，头文件统一存放在QtCore.framework/Headers/子目录下。你当前的编译参数中，-isystem /opt/local/libexec/qt5/lib/QtCore.framework 排在头文件搜索路径的更前位置，当执行#include <QtCore>时，编译器会优先匹配到framework根目录下的二进制QtCore文件，将其作为头文件解析自然会抛出非UTF-8格式的错误。

可执行的修复方案 #

• 方案1：调整头文件搜索路径顺序，将-isystem /opt/local/libexec/qt5/lib/QtCore.framework/Headers 放在 -isystem /opt/local/libexec/qt5/lib/QtCore.framework 之前，让编译器优先匹配Headers目录下的QtCore头文件。
• 方案2（更推荐）：直接删除编译参数中的 -isystem /opt/local/libexec/qt5/lib/QtCore.framework 配置。编译阶段仅需要Headers目录的头文件搜索路径，framework根目录仅需在链接阶段通过-F参数指定即可，不需要加到编译的头文件搜索路径中。
• 额外参数优化：当前编译参数存在冲突项，建议同步清理避免后续问题：
  • 删除-std=c99参数：你编译的是C++代码，保留-std=gnu++11即可，两个标准同时声明会产生未定义行为
  • 删除-Wstrict-prototypes参数：该参数是C语言专属的警告规则，C++编译环境下不生效
  • 删除-D_LINUX_OS_宏定义：当前是macOS平台，该宏定义会干扰Qt头文件的平台适配逻辑

内容的提问来源于stack exchange，提问作者Sam P