【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-1sleep5done

3. 解决特定编译错误

# 查看详细错误信息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/目录下
状态: ✅ 成功运行

【QOwnNotes】编译笔记