【QOwnNotes】编译笔记
📋 环境准备
系统环境
- 操作系统: Windows + MSYS2 UCRT64
- Shell: bash
- 目标: 从源码编译 QOwnNotes (Qt6 版本)
必要软件安装
# 1. 基础开发工具pacman -S --needed mingw-w64-ucrt-x86_64-toolchain\mingw-w64-ucrt-x86_64-cmake\mingw-w64-ucrt-x86_64-ninja# 2. Qt6 开发库pacman -S mingw-w64-ucrt-x86_64-qt6-base\mingw-w64-ucrt-x86_64-qt6-svg\mingw-w64-ucrt-x86_64-qt6-tools\mingw-w64-ucrt-x86_64-qt6-multimedia\mingw-w64-ucrt-x86_64-qt6-websockets\mingw-w64-ucrt-x86_64-qt6-declarative\mingw-w64-ucrt-x86_64-qt6-5compat# 3. 网络工具（解决 SSL 问题）pacman -S ca-certificatescurl🚨 常见问题与解决方案
问题1: SSL 证书错误
error: RPC failed; curl 56 Recv failure: Connection reset by peer SSL certificate OpenSSL verify result: unable to get local issuer certificate解决方案:
# 方法1: 临时禁用 SSL 验证exportGIT_SSL_NO_VERIFY=1gitclone...unsetGIT_SSL_NO_VERIFY# 方法2: 单个命令禁用GIT_SSL_NO_VERIFY=1gitclone...# 方法3: 手动下载（当 git 失败时）curl-L -k https://github.com/user/repo/archive/refs/heads/main.tar.gz -o repo.tar.gztar-xzf repo.tar.gz问题2: 子模块克隆不完整
子模块目录只有.git文件，没有实际内容。
解决方案:
# 批量修复脚本forsubmodulein$(grep"path = ".gitmodules|cut-d'='-f2|tr-d' ');doif[-f"$submodule/.git"]&&[$(ls-A"$submodule"2>/dev/null|wc-l)-le1];thenecho"修复:$submodule"gitsubmodule deinit -f"$submodule"rm-rf"$submodule"GIT_SSL_NO_VERIFY=1gitsubmodule update --init --depth1"$submodule"fidone问题3: 缺失构建文件
CMake 报告找不到源文件，如linenumberarea.h,toolbar_editor.cpp等。
检查步骤:
# 1. 检查文件是否存在findsrc/libraries -name"missing_file.cpp"-type f# 2. 检查子模块状态gitsubmodule status# 3. 重新初始化特定子模块gitsubmodule deinit -f src/libraries/problem_modulerm-rf src/libraries/problem_modulegitsubmodule update --init --depth1src/libraries/problem_module🛠️ 完整编译流程
步骤1: 克隆仓库
# 浅克隆主仓库gitclone --depth1https://github.com/pbek/QOwnNotes.gitcdQOwnNotes# 初始化子模块（可能需多次尝试）exportGIT_SSL_NO_VERIFY=1gitsubmodule update --init --recursive --depth1unsetGIT_SSL_NO_VERIFY步骤2: 配置构建
# 创建构建目录mkdirbuild-qt6cdbuild-qt6# 配置为 Qt6 构建cmake -G"Ninja"-DQON_QT6_BUILD=ON../src如果配置失败:
- 检查错误信息中提到的缺失文件
- 修复对应的子模块
- 重新运行 cmake
步骤3: 编译
# 开始编译（使用多核加速）ninja -j$(nproc)# 或指定核心数ninja -j4步骤4: 运行
# 运行编译的程序（注意：在 build-qt6 目录下运行）cd~/QOwnNotes/build-qt6 ./QOwnNotes.exe📁 项目结构说明
QOwnNotes/ ├── src/ # 主源代码目录 │ ├── CMakeLists.txt # 主构建配置 │ └── ... # 源代码文件 ├── src/libraries/ # 第三方库（子模块） │ ├── botan/ # 加密库 │ ├── md4c/ # Markdown 解析器 │ ├── qhotkey/ # 全局热键支持 │ ├── qmarkdowntextedit/ # Markdown 编辑器组件 │ └── ... # 其他子模块 └── build-qt6/ # 构建目录（自行创建） ├── QOwnNotes.exe # 可执行文件位置 └── ... # 其他构建文件⚙️ CMake 配置选项
| 选项 | 默认值 | 说明 |
|---|---|---|
QON_QT6_BUILD | OFF | 启用 Qt6 构建（设为 ON） |
CMAKE_BUILD_TYPE | Release | 构建类型（Debug/Release） |
QT_VERSION_MAJOR | 5 | Qt 主版本（自动设置） |
完整配置命令:
cmake -G"Ninja"\-DQON_QT6_BUILD=ON\-DCMAKE_BUILD_TYPE=Release\../src🔄 更新与重新编译
更新源代码
cd~/QOwnNotes# 更新主仓库gitpull# 更新所有子模块gitsubmodule update --init --recursive# 重新编译cdbuild-qt6 ninja完全重新构建
cd~/QOwnNotesrm-rf build-qt6mkdirbuild-qt6cdbuild-qt6 cmake -G"Ninja"-DQON_QT6_BUILD=ON../src ninja🐛 调试版本构建
# 创建调试构建mkdirbuild-debugcdbuild-debug cmake -G"Ninja"-DQON_QT6_BUILD=ON -DCMAKE_BUILD_TYPE=Debug../src ninja# 使用 GDB 调试gdb ./QOwnNotes.exe📦 发布准备
收集运行时依赖
# 使用 windeployqt（需要安装）cd~/QOwnNotes/build-qt6 windeployqt QOwnNotes.exe# 手动检查缺失的 DLLldd QOwnNotes.exe|grep"not found"创建便携版
- 复制
build-qt6/QOwnNotes.exe到新目录 - 使用
windeployqt收集所有 Qt DLL - 复制必要的资源文件
- 创建启动脚本
💡 实用技巧
1. 加速编译
# 仅编译更改的部分ninja# 完全重新编译ninja clean ninja# 并行编译（根据 CPU 核心数）ninja -j$(nproc)2. 查看编译进度
# 实时查看进度whiletrue;doclearninja -n2>&1|grep-E"^\[[0-9]+/[0-9]+\]"|tail-1sleep5done3. 解决特定编译错误
# 查看详细错误信息ninja -v2>&1|tail-50# 查看 CMake 缓存变量cmake -L.|grep-i qt📝 学习要点
- Git 子模块管理是大型项目的常见模式
- CMake是现代 C++ 项目的标准构建系统
- Qt6 迁移需要注意 API 变化（如
count()→size()） - MSYS2提供了完整的 Linux 工具链在 Windows 上
- 依赖管理是 C++ 开发的关键挑战
🔗 有用资源
- QOwnNotes GitHub
- Qt6 文档
- CMake 教程
- MSYS2 文档
关键路径说明:
- 源码目录:
~/QOwnNotes/src/ - 构建目录:
~/QOwnNotes/build-qt6/ - 可执行文件:
~/QOwnNotes/build-qt6/QOwnNotes.exe - 运行命令:
cd ~/QOwnNotes/build-qt6 && ./QOwnNotes.exe
最后编译时间: 2024-12-29
编译环境: MSYS2 UCRT64, Qt6, Ninja
运行位置:~/QOwnNotes/build-qt6/目录下
状态: ✅ 成功运行