Qt Creator中.pro文件修改后为何qmake未自动重新运行？

Question

在 Qt Creator 中修改 `.pro` 文件后，qmake 未自动重新运行是常见问题。根本原因在于：Qt Creator 默认仅监控项目文件（如 `.pro`、`.pri`）的**文本内容变更**，但若修改未触发“项目文件已更改”的检测逻辑（例如保存时编码异常、编辑器未真正写入磁盘、或使用外部工具修改后未刷新），则 IDE 不会主动调用 qmake。此外，当项目已配置为“Shadow Build”且构建目录被手动清理、或 `.pro.user` 中 `QMAKE_AUTO_RUN` 被禁用/损坏时，自动 qmake 也会失效。更隐蔽的情况是启用了“仅在构建前运行 qmake”（Options → Build & Run → General → “Run qmake when project file changes” 未勾选），或当前套件（Kit）未正确关联 qmake 路径。该问题会导致新增的源文件、宏定义或依赖项不生效，编译失败或行为异常——表面看是缓存问题，实则是 Qt Creator 的项目变更感知与 qmake 触发机制脱节所致。

Answer 1

```html

一、现象层：qmake 未自动触发的典型症状

• 修改 .pro 文件新增 SOURCES += newfile.cpp 后，构建时提示“undefined reference”或文件未参与编译；
• 添加 DEFINES += DEBUG_LOG，但预处理宏在代码中始终未生效；
• 切换 Kit 后，.pro 中的 win32: LIBS += -lws2_32 突然失效，且无任何警告；
• Qt Creator 底部状态栏未显示 “Running qmake…” 提示，构建日志中也缺失 qmake -o Makefile ... 行；
• 外部编辑器（如 VS Code）保存 .pro 后，Qt Creator 界面无“文件已修改”标记，亦不弹出重载提示。

二、机制层：Qt Creator 的 qmake 自动触发原理

Qt Creator 并非监听文件系统 inotify/fsevents，而是采用基于文本内容哈希比对的轻量级变更检测：

1. 首次加载项目时，为 .pro、.pri、.prf 等文件生成 SHA-256 内容快照，存于内存缓存；
2. 每次 Ctrl+S 或焦点离开编辑器时，重新计算当前文件哈希并与缓存比对；
3. 仅当哈希不一致且满足 QMAKE_AUTO_RUN == true（由 .pro.user 控制）时，才触发 qmake 调用；
4. 该机制绕过文件时间戳（mtime），故 touch .pro 或 Git checkout 不会触发自动 qmake —— 这是设计使然，非 bug。

三、根因层：五大类失效场景与验证路径

类别	技术表征	快速验证命令
编码/写入异常	文件末尾多出 BOM 或 \r\n/\n 混用导致哈希误判	xxd -l 16 myproject.pro | head -1
.pro.user 损坏	QMAKE_AUTO_RUN=false 或键值被覆盖为字符串 "false"（应为布尔）	grep -A2 "QMAKE_AUTO_RUN" myproject.pro.user
Shadow Build 异常	构建目录被 rm -rf build-* 清理后未重置 IDE 构建上下文	Qt Creator → Projects → Build Settings → “Build directory” 是否仍指向已删路径？

四、诊断层：结构化排错流程图

flowchart TD A[修改 .pro 后 qmake 未运行？] --> B{是否在 Qt Creator 内编辑并 Ctrl+S？} B -->|否| C[外部修改 → 手动点击 “重新加载项目”] B -->|是| D[检查 Options → Build & Run → General
“Run qmake when project file changes” 是否勾选？] D --> E{Kit 是否配置有效 qmake？} E -->|否| F[Projects → Kits → 选择 Kit → qmake path 是否指向 qt5/qmake 或 qt6/qmake？] E -->|是| G[查看 .pro.user 中 QMAKE_AUTO_RUN 值] G --> H[用文本编辑器打开 .pro.user，搜索 QMAKE_AUTO_RUN] H --> I{值为 true？} I -->|否| J[手动设为 true，重启 Qt Creator] I -->|是| K[执行 Build → “Run qmake” 手动触发，观察输出]

五、解决层：生产环境推荐操作集

• 预防性配置：在 Options → Build & Run → General 中强制启用 “Run qmake when project file changes”，并勾选 “Always run qmake before building”；
• Shadow Build 安全清理：不直接 rm -rf build-dir，而使用 Qt Creator → Build → “Clean Project” 或右键项目 → “Clean”；
• 自动化修复脚本（适用于 CI/CD 或团队标准化）：

  #!/bin/bash
  # fix-pro-user.sh
  sed -i 's/\"QMAKE_AUTO_RUN\".*false/\"QMAKE_AUTO_RUN\" : true/' *.pro.user
  sed -i 's/\"QMAKE_AUTO_RUN\".*0/\"QMAKE_AUTO_RUN\" : true/' *.pro.user
  

• 终极兜底方案：在 .pro 文件末尾添加唯一时间戳注释，强制改变哈希：# AUTO-TRIGGER-ON-SAVE: $$system(date +%s)（需 Qt 5.14+ 支持 $$system）；

六、进阶层：理解 qmake 触发与构建系统的耦合关系

Qt Creator 的 qmake 触发逻辑并非孤立存在，它深度嵌入构建生命周期：

• 当启用 “Shadow Build” 时，qmake 输出的 Makefile 和 moc_*.cpp 全部生成在独立构建目录，IDE 通过解析 Makefile 中的 QMAKE_TARGET 和 OBJECTS 变量反向构建符号索引；
• 若 qmake 未运行，moc 头文件不会生成，Clang Code Model 将无法解析 Q_OBJECT 类，导致跳转、补全、重构全部失效；
• 更关键的是：.pro.user 中的 QMAKE_AUTO_RUN 实际控制的是 ProjectExplorer::Project::scheduleQMake() 的调用门控——这是 Qt Creator 5.0+ 的私有 API 层决策点。

```