使用 Nix 安装与管理 QOwnNotes：从 NixOS、Linux 到 macOS 的完整指南

• 桌面应用

QOwnNotes 是一款支持 Markdown 与 Nextcloud / ownCloud 集成的纯文本笔记与待办事项管理应用。本文聚焦于官方支持的一条安装路径——Nix 包管理器：以仓库中的 Nix 打包定义 为骨架，讲解包名、构建特性、各平台的安装方式、运行命令、命令行片段管理器qc的安装，以及 Linux 桌面钥匙串（Secret Service）相关的常见问题与排查方案。读完本文，你将掌握在 NixOS、其他 Linux 发行版、macOS 甚至 Windows（经 WSL）上通过 Nix 安装 QOwnNotes 的完整实操流程，并理解其底层打包实现。

Nix 与 QOwnNotes：一条声明式、可复现的安装路径

Nix 是一款函数式、声明式的包管理器，既服务于专门的 Linux 发行版 NixOS，也可以独立安装在绝大多数 Linux 发行版、macOS 与 Windows（通常借助 WSL）上。它最大的价值在于可复现性：同样的包定义在任何机器上都会构建出行为一致的产物。

QOwnNotes 官方文档（见 网页文档原文）明确指出，你可以在以下环境中通过 Nix 安装 QOwnNotes：

• NixOS
• 其他Linux发行版
• macOS
• Windows

Nix 仓库中的包名是qownnotes，可以从 NixOS 包搜索中检索到。文档特别提示：建议使用 NixOS Unstable 通道（unstable channel），以获得最新版本的 QOwnNotes。

注：从仓库的打包定义看，default.nix 中meta.platforms = lib.platforms.unix，即包本身面向 Unix 系平台；在 Windows 上通常是通过 WSL 中的 Nix 环境来安装与运行。

Nix 包的构建特性：Qt6、系统 botan3、libgit2 与 Shell 补全

Nix 安装的 QOwnNotes 包并非简单的二进制搬运，它有以下明确特性（官方文档声明，且与仓库打包定义一一对应）：

• 基于 Qt6 构建：CMake 编译标志-DQON_QT6_BUILD=ON；
• 使用系统 botan3 库：-DBUILD_WITH_SYSTEM_BOTAN=ON，即加解密功能不内置 Botan，而是链接发行版提供的 botan3；
• 使用系统 libgit2：-DBUILD_WITH_LIBGIT2=ON，用于笔记的 Git 版本管理能力；
• 集成 aspell 拼写检查：-DBUILD_WITH_ASPELL=ON；
• 提供 fish 与 bash 的 Shell 补全集成：安装时会同时为qownnotes与QOwnNotes两个命令安装补全脚本。

这些标志全部可以在仓库根目录的 default.nix 中看到：

cmakeFlags = [ "-DQON_QT6_BUILD=ON" "-DBUILD_WITH_SYSTEM_BOTAN=ON" "-DBUILD_WITH_LIBGIT2=ON" "-DBUILD_WITH_ASPELL=ON" ] ++ lib.optionals useQlitehtml [ "-DUSE_QLITEHTML=ON" "-DQLITEHTML_LIBRARY_TYPE=STATIC" ];

此外，Linux 构建还会额外引入libsecret与qtwayland作为构建依赖（见 default.nix），为桌面钥匙串集成和 Wayland 会话做好准备。

安装 QOwnNotes

在 NixOS 上安装

NixOS 采用声明式配置，推荐将包加入系统环境。在/etc/nixos/configuration.nix中写入：

{ config, pkgs, ... }: { environment.systemPackages = with pkgs; [ qownnotes ]; }

然后重建系统：

sudo nixos-rebuild switch

在非 NixOS 的 Linux 与 macOS 上安装

在其他发行版或 macOS 上使用 Nix 包管理器时，可以用传统的nix-env安装（需先将unstable通道切换为默认，以获得最新版本）：

nix-env -iA nixpkgs.qownnotes

使用 Flakes 的现代方式则是：

nix profile install nixpkgs#qownnotes

这两条命令是 Nix 包管理器的通用用法；仓库内并不包含nix-env/nix profile的具体封装，实际执行时请确保你的 Nix 环境与通道配置正确。

验证安装：运行命令

安装完成后，你可以通过以下两个命令启动 QOwnNotes：

qownnotes QOwnNotes

大小写两种写法都可用，这并非偶然。查看 default.nix 可以看到打包时的处理逻辑：

• 在Linux上，安装阶段会为QOwnNotes创建一个小写软链接qownnotes，因此两个命令等价；
• 在macOS上，则是把二进制从QOwnNotes重命名为小写的qownnotes。

所以在 macOS 上，QOwnNotes这种写法来自打包前应用自带的命名，而qownnotes则是 Nix 包统一的小写入口；meta.mainProgram = "qownnotes"也印证了这一点（见 default.nix）。

从仓库 Flake 直接构建

如果你希望使用仓库最新的开发状态，仓库根目录的 flake.nix 提供了完整的可构建包集合，支持x86_64-linux、aarch64-linux、x86_64-darwin、aarch64-darwin四个平台。可用的包属性包括：

例如：

nix build .#qownnotes-qt6

构建产物中的可执行文件即为result/bin/QOwnNotes（Linux 下同时存在result/bin/qownnotes软链接）。其中的 Qt5 变体对应仓库 build-systems/nix/default-qt5.nix，它使用 qmake 构建并强制USE_SYSTEM_BOTAN=0（Qt5 构建需要内置 Botan2）。

安装命令行片段管理器 qc

QOwnNotes 生态中还有一个命令行工具qc（QOwnNotes Command-line Snippet Manager），用于在命令行中管理代码片段，同样可以通过 Nix 安装（官方文档说明其存在于 Nix 包仓库中，包名同为qc）。

官方文档给出了一条可立即试用的命令：

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

它会在一个临时 Nix 环境中拉取qc包并执行qc exec，适合在不污染系统环境的情况下快速体验。

macOS：原生支持 x86 与 Apple Silicon

官方文档特别强调：在macOS上，Nix 安装的 QOwnNotes 包原生支持 x86 与 Apple Silicon（即 Intel 与 M 系列芯片）。

这一结论同样有源码依据：flake.nix 声明的支持系统中包含x86_64-darwin与aarch64-darwin两个 macOS 平台，打包定义中也为 Darwin 分支准备了makeWrapper等构建依赖（见 default.nix）。也就是说，无论你的 Mac 是 Intel 还是 Apple Silicon，都可以获得原生二进制，无需依赖 Rosetta 转译。

解决 Linux 上的钥匙串写入失败问题

在 Linux 上运行 QOwnNotes 时，如果日志中出现：

Could not write secret to keychain

说明应用无法向桌面密钥环（keychain）写入密钥。官方文档给出了标准处理方式：安装一个 Secret Service 实现，然后重启桌面会话。具体到不同桌面环境：

• GNOME 及其他基于 Secret Service 的桌面：向你的环境中加入gnome-keyring、libsecret和seahorse；
• KDE Plasma：加入 KWallet 支持，例如kdePackages.kwalletmanager与kdePackages.kwallet。

例如在 NixOS 的configuration.nix中：

environment.systemPackages = with pkgs; [ gnome-keyring libsecret seahorse ];

在 KDE Plasma 上则替换为：

environment.systemPackages = with pkgs; [ kdePackages.kwalletmanager kdePackages.kwallet ];

文档还给出了一个重要的回退机制：如果桌面钥匙串不可用，QOwnNotes 会自动回退到传统加密方式。因此即使暂时无法配置密钥环，应用也不会完全失去加密能力。

这条注意事项在打包层也有呼应：Linux 构建中libsecret被显式加入buildInputs（见 default.nix），确保应用链接到 Secret Service 相关的系统库。

深度剖析：Nix 打包定义的实现细节

理解 default.nix 能帮助你更精准地排错与定制。几个值得注意的实现细节：

1. 版本号自动读取：打包定义通过正则从src/version.h中提取#define VERSION "x.y.z"作为包版本（default.nix），保证 Nix 包版本与上游源码一致，无需手动维护。
2. Shell 补全的生成方式：安装阶段通过xvfb-run在虚拟显示器中运行QOwnNotes --completion bash与--completion fish，将生成的补全脚本交给installShellCompletion安装（default.nix）。也就是说，补全脚本是由程序自身在打包时实时生成的。对应地，源码在 main.cpp 中注册了--completion命令行选项，并在 utils/cli.cpp 中实现了 fish 与 bash 补全脚本的生成逻辑（zsh 生成器在源码中标记为尚未完成）。
3. Linux / macOS 的可执行文件命名差异：前文已述，Linux 用软链接、macOS 用重命名，最终统一提供qownnotes小写入口。
4. 可选开关useQlitehtml：通过 flake 传入useQlitehtml = true可以启用仓库自带的 qlitehtml 渲染后端（对应-DUSE_QLITEHTML=ON与-DQLITEHTML_LIBRARY_TYPE=STATIC）。

开发者视角：Nix 开发环境与自动化验证

如果你打算为 QOwnNotes 贡献代码，仓库同样提供了完整的 Nix 开发体验：

• 开发 Shell：devenv.nix 基于 devenv 构建，包含 Qt6 工具链、cmake、just、botan3、libsecret 等，进入项目目录即自动获得一致的构建环境；它还通过update-qmake-symlinks脚本在bin/下维护 qmake5/qmake6 软链接，便于 Qt Creator 与 CLion 使用（对应脚本 scripts/nix-update-qmake-symlinks.sh）。
• NixOS 虚拟机测试：tests/vm/qownnotes.nix 定义了一个完整的 NixOS 测试节点，自动验证qownnotes --version输出、首次启动欢迎向导、创建笔记目录、通过Ctrl+N新建并保存笔记等关键流程，测试通过 OCR 与文本断言逐项检查。该测试在 flake.nix 中被注册为checks.x86_64-linux.qownnotes，可用nix flake check运行。
• CLion 构建辅助：若在 CLion 中直接构建 Qt6 应用遇到Could not find the Qt platform plugin "xcb"错误，可使用仓库提供的 scripts/nix-wrap-run-qt6-app.sh，它会借助wrapQtAppsHook对本地构建产物进行包装后再启动。

常见问题速查

小结

Nix 为 QOwnNotes 提供了声明式、可复现的安装路径：一个包名qownnotes覆盖 NixOS、其他 Linux、macOS 与 Windows（经 WSL）四种场景；包基于 Qt6 构建并复用系统 botan3、libgit2 与 aspell，还自带 bash/fish 补全；macOS 原生支持 Intel 与 Apple Silicon；qc命令行片段管理器亦可同源安装。若遇到钥匙串问题，按桌面环境安装对应的 Secret Service 组件即可。深入阅读 default.nix 与 flake.nix，还能看到版本自动提取、补全脚本自生成、Linux/macOS 命名适配等工程细节，这正是 Nix 打包的魅力所在。

• 桌面应用