MacOS编译Notepadqq报错QT未知模块webkitwidgets

问题描述 #

在macOS平台构建Notepadqq，执行make命令时构建失败，核心报错为WARNING: Project ERROR: Unknown module(s) in QT: webkitwidgets，最终make进程返回错误码3。

环境与已尝试操作 #

• 运行系统为macOS Monterey 12.4 (21F79)，最初通过brew安装QT 6.3.0版本编译，触发上述webkitwidgets模块缺失错误，编译过程中多语言翻译文件可正常生成
• 更换QT 5.15.3版本重试，configure阶段检测显示Qt5Core、Qt5Gui、Qt5Network、Qt5WebKit、Qt5Widgets、Qt5WebKitWidgets、Qt5PrintSupport、Qt5Svg等依赖库均未找到，执行make时仍出现相同webkitwidgets模块缺失报错，同时提示当前使用的12.3版本平台SDK未经过QT 5.15.3版本兼容性测试，属于非支持配置，可能引发构建问题。

QT 6.3.0版本编译完整日志 #

$ make
cd src/ui/ && ( test -e Makefile || /usr/local/Cellar/qt/6.3.0/bin/qmake -o Makefile /Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/ui.pro PREFIX= QMAKE_CXX=c++ 'QMAKE_CXXFLAGS= ' QMAKE_LFLAGS= LRELEASE=/usr/local/Cellar/qt/6.3.0/bin/lrelease CONFIG+= ) && /Library/Developer/CommandLineTools/usr/bin/make -f Makefile 
Project MESSAGE: Release build
WARNING: Project ERROR: Unknown module(s) in QT: webkitwidgets
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_de.qm'...
    Generated 348 translation(s) (348 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_es.qm'...
    Generated 365 translation(s) (365 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_fr.qm'...
    Generated 345 translation(s) (345 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_hu.qm'...
    Generated 453 translation(s) (453 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_it.qm'...
    Generated 345 translation(s) (345 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_ja.qm'...
    Generated 344 translation(s) (344 finished and 0 unfinished)
    Ignored 1 untranslated source text(s)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_pl.qm'...
    Generated 348 translation(s) (348 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_pt.qm'...
    Generated 345 translation(s) (345 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_ru.qm'...
    Generated 328 translation(s) (326 finished and 2 unfinished)
    Ignored 17 untranslated source text(s)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_sl.qm'...
    Generated 345 translation(s) (345 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_sv.qm'...
    Generated 359 translation(s) (359 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_uk.qm'...
    Generated 365 translation(s) (365 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_zh.qm'...
    Generated 363 translation(s) (363 finished and 0 unfinished)
Project ERROR: Unknown module(s) in QT: webkitwidgets
make: *** [sub-src-ui-make_first] Error 3

QT 5.15.3版本编译完整日志 #

C02XP51WJG5J:notepadqq-1.4.0 vsamula$ ./configure 
checking for QT5 qmake... /usr/local/Cellar/qt@5/5.15.3/bin/qmake
checking for lrelease... /usr/local/Cellar/qt@5/5.15.3/bin/lrelease
checking for c++... /usr/bin/c++
checking whether c++ compiler builds test program... ok
checking whether c++ compiler supports -std=c++0x... ok
checking whether compiled test program works... ok
checking for make... /usr/bin/make
checking for pkg-config... /usr/local/bin/pkg-config
checking for Qt5Core library... not found!
checking for Qt5Gui library... not found!
checking for Qt5Network library... not found!
checking for Qt5WebKit library... not found!
checking for Qt5Widgets library... not found!
checking for Qt5WebKitWidgets library... not found!
checking for Qt5PrintSupport library... not found!
checking for Qt5Svg library... not found!
generate Makefile... Info: creating stash file /Users/vsamula/Downloads/notepadqq-1.4.0/.qmake.stash
done

C02XP51WJG5J:notepadqq-1.4.0 vsamula$ make
cd src/ui/ && ( test -e Makefile || /usr/local/Cellar/qt@5/5.15.3/bin/qmake -o Makefile /Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/ui.pro PREFIX= QMAKE_CXX=c++ 'QMAKE_CXXFLAGS= ' QMAKE_LFLAGS= LRELEASE=/usr/local/Cellar/qt@5/5.15.3/bin/lrelease CONFIG+= ) && /Library/Developer/CommandLineTools/usr/bin/make -f Makefile 
Project MESSAGE: Release build
WARNING: Project ERROR: Unknown module(s) in QT: webkitwidgets
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_de.qm'...
    Generated 348 translation(s) (348 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_es.qm'...
    Generated 365 translation(s) (365 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_fr.qm'...
    Generated 345 translation(s) (345 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_hu.qm'...
    Generated 453 translation(s) (453 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_it.qm'...
    Generated 345 translation(s) (345 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_ja.qm'...
    Generated 344 translation(s) (344 finished and 0 unfinished)
    Ignored 1 untranslated source text(s)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_pl.qm'...
    Generated 348 translation(s) (348 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_pt.qm'...
    Generated 345 translation(s) (345 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_ru.qm'...
    Generated 328 translation(s) (326 finished and 2 unfinished)
    Ignored 17 untranslated source text(s)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_sl.qm'...
    Generated 345 translation(s) (345 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_sv.qm'...
    Generated 359 translation(s) (359 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_uk.qm'...
    Generated 365 translation(s) (365 finished and 0 unfinished)
Updating '/Users/vsamula/Downloads/notepadqq-1.4.0/src/ui/../translations/notepadqq_zh.qm'...
    Generated 363 translation(s) (363 finished and 0 unfinished)
Project WARNING: Qt has only been tested with version 11.0 of the platform SDK, you're using .
Project WARNING: This is an unsupported configuration. You may experience build issues, and by using
Project WARNING: the 12.3 SDK you are opting in to new features that Qt has not been prepared for.
Project WARNING: Please downgrade the SDK you use to build your app to version 11.0, or configure
Project WARNING: with CONFIG+=sdk_no_version_check when running qmake to silence this warning.
Project ERROR: Unknown module(s) in QT: webkitwidgets
make: *** [sub-src-ui-make_first] Error 3

根因说明 #

• QT 6.x版本已完全移除废弃的QtWebKit模块，使用QT6编译必然触发webkitwidgets缺失错误，必须使用QT5版本编译
• brew源中qt@5包默认不包含QtWebKit组件，该组件被拆分为独立包，且QT5的pkg-config路径未默认加入系统查找路径，导致configure阶段检测不到所有QT5依赖库
• QT 5.15.3对macOS 12.3 SDK的兼容性警告不影响实际编译，添加编译参数即可跳过检查，无需降级SDK。

修复步骤 #

1. 清理旧编译缓存，在源码根目录执行以下命令，删除残留配置避免干扰：

make distclean
rm -f Makefile .qmake.stash src/ui/Makefile

2. 安装缺失的QT5 WebKit组件：

brew install qt5-webkit

3. 配置QT5环境变量，让编译脚本和pkg-config能正确找到依赖路径：

Intel芯片Mac执行：

export PATH="/usr/local/opt/qt@5/bin:$PATH"
export PKG_CONFIG_PATH="/usr/local/opt/qt@5/lib/pkgconfig:/usr/local/opt/qt5-webkit/lib/pkgconfig:$PKG_CONFIG_PATH"

M系列芯片Mac执行：

export PATH="/opt/homebrew/opt/qt@5/bin:$PATH"
export PKG_CONFIG_PATH="/opt/homebrew/opt/qt@5/lib/pkgconfig:/opt/homebrew/opt/qt5-webkit/lib/pkgconfig:$PKG_CONFIG_PATH"

4. 重新执行配置和编译，添加参数跳过SDK版本检查：

./configure -config sdk_no_version_check
make -j$(sysctl -n hw.ncpu)

5. 编译完成后执行sudo make install即可完成安装。

若仍提示找不到QT5依赖，可手动指定qmake路径执行配置：./configure --qmake <你的qt5 qmake实际路径> -config sdk_no_version_check

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