企业官网建设流程全解析

• 桌面应用

QOwnNotes 是一款支持 Markdown 的纯文本笔记与待办事项管理器，并深度集成了 Nextcloud / ownCloud。在 macOS 上，官方提供了基于 Qt6 构建的通用二进制（Universal Binary）磁盘映像，同时社区维护了 Homebrew cask 与 Nix 包，三者覆盖了从「拖拽即装」到「命令行管理」的全部常见需求。读完本文，你将掌握在 macOS（含 Intel 与 Apple Silicon）上安装 QOwnNotes 的完整流程、Gatekeeper 隔离解除方法，以及 Qt5 旧版 DMG 的适用边界与升级注意事项。

本文内容以仓库中的官方安装文档 webpage/src/installation/macos.md（其波兰语版本为 webpage/src/pl/installation/macos.md）为主体骨架，并结合仓库内 DMG 构建脚本、Nix 打包定义与更新服务源码进行实现层面的印证与扩充。

方式一：通过 DMG 磁盘映像安装（官方推荐）

这是官方提供的标准安装方式，适合大多数普通用户。

1. 从 QOwnNotes 的Release 页面下载最新的macOS 磁盘映像（DMG）；
2. 双击打开下载得到的 DMG 文件；
3. 将QOwnNotes应用图标拖拽到应用程序（Applications）文件夹中；
4. 首次打开时，需要右键点击应用并选择打开（Open），才能正常启动 QOwnNotes。

提示：DMG 映像内部会放置一个指向/Applications的符号链接（见下文源码佐证），拖拽安装是官方设计的标准流程。

版本选择：Qt6 通用二进制与 Qt5 旧版

官方在 GitHub Release 中同时发布两种 DMG，选择时需要区分清楚：

对于大多数用户，应当优先选择QOwnNotes.dmg。作为参照，当前仓库版本号为26.10.3（见 src/version.h），即该版本对应生成的 DMG 即为此版本。

关于 Qt5 旧版 DMG，仓库中的 docs/qt5-retirement-recommendation.md 明确了其定位：Legacy macOS DMG 暂时保留在 GitHub 发布流程中，供无法运行 Qt6 构建的操作系统用户使用，但 Qt5 相关的发布通道正在逐步退役。这意味着 Qt5 DMG 不会获得新功能迭代，且必须手动检查并下载新版，安装后也请留意向 Qt6 版本迁移。

处理「无法验证开发者」与隔离属性

从网上下载的未签名或临时签名的应用，首次启动时 macOS 的 Gatekeeper 可能会拦截，并弹出如下错误：

QOwnNotes.app cannot be opened because the developer cannot be verified

此时有两种处理方式：

方式 A：通过系统设置放行

前往 macOS 的安全性与隐私（Security & Privacy）设置，在下方提示区域点击仍然打开（Open Anyway），然后回到应用再次启动。

方式 B：使用命令行移除隔离属性

在终端中执行以下命令，将应用从 quarantine（隔离）状态中取出：

xattr -r -d com.apple.quarantine /Applications/QOwnNotes.app

xattr -r表示递归处理应用包内的所有文件，-d com.apple.quarantine删除表示「下载来源」的扩展属性，执行后应用即可正常打开。

内部更新器：右下角即最新版本

QOwnNotes 使用内置的内部更新器（internal updater）完成自我升级，你可以在应用界面的右下角看到当前的最新版本号。其底层实现位于 src/services/updateservice.cpp：UpdateService::checkForUpdates()会向https://api.qownnotes.org/latest_releases/发起请求，携带当前版本号、平台、CPU 架构与操作系统信息，从而判断是否有新版本可下载。因此只要安装的是 Qt6 的QOwnNotes.dmg，后续升级基本无需人工干预。

方式二：通过 Homebrew 安装

如果你已经在使用 Homebrew 管理 macOS 软件，这是最省事的方式。

Homebrew 官方 formulae 站点上维护着社区托管的 QOwnNotescask，安装命令只需一条：

brew install qownnotes

该方式由社区维护，包名与官方应用一致，安装后同样可以在「应用程序」文件夹中找到 QOwnNotes，并与 DMG 安装版保持相同的功能与更新行为。

方式三：通过 Nix 安装（原生支持 Intel 与 Apple Silicon）

对于使用 Nix 包管理器（波兰语版本见 webpage/src/pl/installation/nix.md）说明：

• Nix 包适用于NixOS、其他 Linux 发行版、macOS 乃至 Windows；
• 在macOS 上原生支持 x86（Intel）与 Apple Silicon（arm64）；
• 包基于Qt6构建，并使用系统级botan3加密库与libgit2；
• 提供fish 与 bash的 shell 补全集成。

安装后，即可通过以下任一命令启动：

qownnotes # 或 QOwnNotes

建议：优先使用NixOS Unstable channel以获得最新版本的 QOwnNotes。

从源码可以印证上述特性：

• flake.nix 中声明的支持系统列表包含x86_64-darwin与aarch64-darwin，即 Intel 与 Apple Silicon 两种 macOS 架构，默认包由qt6Packages.callPackage构建；
• default.nix 中，macOS 分支（stdenv.hostPlatform.isDarwin）会额外引入makeWrapper，并在安装阶段将应用二进制改名为小写的qownnotes，同时生成 bash 与 fish 的 shell 补全，mainProgram也声明为qownnotes，这与官方文档描述的启动命令完全一致。

如果你还想体验官方命令行片段管理器qc，也可以通过 Nix 安装并临时试运行：

nix-shell -p qc --run "qc exec"

源码视角：Qt6 DMG 是如何构建出来的

为了更清楚地理解「为什么QOwnNotes.dmg是通用二进制、为什么要求 macOS 13」，可以查看仓库中的 DMG 构建脚本 build-systems/github/macos/create-dmg-qt6.sh。该脚本（用于 GitHub Actions 发布流程）的核心步骤包括：

1. 修正应用包的 bundle identifier 并写入版本号（CFBundleVersion/CFBundleShortVersionString）；
2. 将编译好的翻译文件（languages/*.qm）与 Qt 基础翻译文件拷贝进应用包；
3. 调用 Qt 自带的macdeployqt（带-codesign=-参数）部署 Qt 框架依赖；
4. 执行 build-systems/github/macos/bundle-openssl-qt6.sh 将 OpenSSL 3 以双架构（arm64 + x86_64）形式捆绑进应用（Qt 的 OpenSSL TLS 后端需要这些库动态加载，而 SecureTransport 回退方案不支持 TLS 1.3）；
5. 在 DMG 临时目录中创建指向/Applications的符号链接；
6. 用hdiutil create生成UDBZ压缩格式、HFS+文件系统的磁盘映像。

同时，build-systems/github/macos/bundle-openssl-qt6.sh 中MACOSX_DEPLOYMENT_TARGET的默认值为13.0，即构建产物面向 macOS 13 及更高版本——这正是官方文档要求macOS 13（Ventura）及以上才能运行QOwnNotes.dmg的底层原因。仓库中另有旧版构建脚本 build-systems/github/macos/create-dmg.sh，对应历史 Qt5 产物的制作流程。

安装后的验证与日常维护

完成安装后，可以从以下几个方面确认环境正常：

1. 启动验证：首次启动若被 Gatekeeper 拦截，按上文「安全设置放行」或xattr命令处理；
2. 版本确认：观察应用右下角显示的最新版本号，与 src/version.h 中记录的当前仓库版本（26.10.3）对照，可判断是否为最新发布；
3. 更新策略：
   • Qt6 DMG 与 Homebrew 安装版：依靠内部更新器或包管理器自动升级；
   • Qt5 旧版 DMG：无法使用内部更新器，需定期手动前往 Release 页面下载新版，并建议尽快迁移至 Qt6 版本（参考 docs/qt5-retirement-recommendation.md 中的退役规划）。

总而言之，macOS 用户可以根据自身习惯在三条安装路径中选择：追求官方最新体验选DMG（Qt6 通用二进制），习惯 Homebrew 一条命令管理选brew install qownnotes，深度使用 Nix 生态则选Nix 包（同样原生支持 Intel 与 Apple Silicon）。无论哪种方式，安装后的使用体验完全一致，且都能与 Nextcloud / ownCloud 笔记同步能力无缝衔接。

• 桌面应用