企业官网建设流程全解析

• 桌面应用

QOwnNotes 是一款支持 Markdown 与 Nextcloud / ownCloud 集成的纯文本笔记和待办事项管理应用。本指南以仓库官方文档 webpage/src/getting-started/cli-parameters.md（及其中文站点的韩文翻译版 webpage/src/ko/getting-started/cli-parameters.md）为主线，结合源码逐项解析 QOwnNotes 命令行接口的全部参数。读完本文，你将掌握：用--session隔离配置排查安装问题、用--dump-settings一键导出诊断信息、在命令行中解密加密笔记，以及在应用启动后自动触发菜单动作（含脚本自定义动作）的完整实战方案。

参数总览

在命令行接口（CLI）中，可以使用以下参数控制应用的启动行为：

这些参数全部由 src/main.cpp 中的mainStartupMisc()通过 Qt 的QCommandLineParser注册并解析（见 src/main.cpp）；同时main()入口还有一段手工参数扫描，用于在 Qt 应用对象构造之前提前决定单实例模式、会话名、启动动作等全局属性（见 src/main.cpp）。两处解析相互配合：手工扫描决定"怎么启动"，QCommandLineParser负责"启动后做什么"。

不同操作系统下的命令形式

命令行调用方式因操作系统而异：

基础信息参数：--help 与 --version

• --help（短形式-h）立即显示命令行帮助画面。源码特意没有使用 Qt 默认的parser.addHelpOption()（因为默认实现会附带一个无法工作的--help-all选项），而是手工注册-h/--help选项（见 src/main.cpp），命中后直接调用parser.showHelp()输出帮助并结束（见 src/main.cpp）。
• --version只打印一行版本信息后立即退出，不会启动图形界面。在main()的手工参数扫描中，命中该参数时直接向 stdout 输出QOwnNotes <VERSION>并exit(0)（见 src/main.cpp）。版本号定义于 src/version.h。

QOwnNotes --help QOwnNotes --version

运行模式参数：便携、会话隔离与多实例

--portable：便携模式

--portable让 QOwnNotes 以"绿色软件"形态运行，所有数据都保存在可执行文件所在目录下，不污染系统用户目录：

• 设置文件切换为 INI 格式，并存放于可执行文件旁的Data目录。源码在便携模式下调用QSettings::setDefaultFormat(QSettings::IniFormat)，并将UserScope路径指向Utils::Misc::portableDataPath()（见 src/main.cpp）。
• portableDataPath()的实现（见 src/utils/misc.cpp）对 AppImage 优先使用$APPIMAGE环境变量解析可执行文件所在目录，对普通可执行文件使用QCoreApplication::applicationDirPath()，最终统一追加/Data子目录并自动创建。
• 便携模式还会通过环境变量QML_DISABLE_DISK_CACHE=true禁用 QML 磁盘缓存，因为该缓存路径无法被重定向（见 src/main.cpp）。

QOwnNotes --portable

--session：隔离配置文件上下文

--session <name>让应用在独立上下文中运行：设置与内部文件都不会与主配置互相干扰。其原理是：main()读取会话名后将其拼接到应用名后缀中——QCoreApplication::setApplicationName("QOwnNotes" + appNameAdd)，其中appNameAdd形如-<session>（见 src/main.cpp 与 src/main.cpp）。由于 Qt 的设置文件路径由"组织名 + 应用名"决定，会话名不同即意味着完全独立的配置文件与内部数据库。

::: tip QOwnNotes 安装过程中遇到问题、又不想丢失现有配置时，可以用--session以一套全新配置启动应用进行排查：

QOwnNotes --session test

:::

--allow-multiple-instances：允许多实例

默认情况下，QOwnNotes 通过SingleApplication库实现单实例限制（allowOnlyOneAppInstance默认开启，还会读取设置项allowOnlyOneAppInstance，见 src/main.cpp）。传入--allow-multiple-instances会把该开关置为false，从而允许多个实例同时运行（见 src/main.cpp）。

QOwnNotes --allow-multiple-instances

注意：单实例模式仍然生效时，第二个实例会收到"已有另一个 QOwnNotes 实例在运行"的提示并直接退出（见 src/main.cpp）。

--clear-settings：清空设置

--clear-settings清空全部设置后启动应用。源码中的处理更为细致：清空前先通过CryptoService::keychainReferencesFromSettings()收集密钥环（Keychain）中相关条目的引用，清空后同步删除这些密钥条目，避免残留孤儿密钥（见 src/main.cpp）。

QOwnNotes --clear-settings

诊断调试参数：--dump-settings

--dump-settings是排查问题的利器：它以 GitHub Markdown 格式输出应用与环境的完整设置转储，然后退出应用。输出由Utils::Misc::generateDebugInformation()生成（见 src/utils/misc.cpp），内容包括当前日期、版本号、构建号、平台、操作系统、Qt 版本（编译期与运行期）、便携模式状态、设置文件路径、笔记文件夹、云连接与已启用脚本等信息。源码还会把转储文本同时写入系统剪贴板（QClipboard::setText(dump)），方便直接粘贴（见 src/main.cpp）。

QOwnNotes --dump-settings

要把设置转储直接复制到剪贴板，可以配合各系统的管道工具：

# Linux 下用 xclip 将设置转储复制到剪贴板 QOwnNotes --dump-settings | xclip -selection clipboard # Linux 下用 xsel 复制到剪贴板 QOwnNotes --dump-settings | xsel --clipboard # macOS 下用 pbcopy 复制到剪贴板 QOwnNotes --dump-settings | pbcopy # Windows 下用 clip 复制到剪贴板 QOwnNotes --dump-settings | clip

Shell 补全参数：--completion

--completion <shell>用于生成 shell 补全脚本，目前支持fish与bash，实现位于 src/utils/cli.cpp：

• generateFishCompletionScript()（src/utils/cli.cpp）为每个长选项生成complete -c QOwnNotes -l <name> -d "<描述>"形式的补全条目；
• generateBashCompletionScript()（src/utils/cli.cpp）生成一个_QOwnNotes()补全函数，并对带文件参数的选项启用文件名补全；
• src/main.cpp 按参数值分发：值为fish或bash时生成对应脚本并退出；其他值时报错退出。源码中还保留了generateZshCompletionScript()的占位实现（src/utils/cli.cpp），但标注TODO: Doesn't work yet，尚未启用。

用法示例：

# 生成 bash 补全并追加到 bashrc QOwnNotes --completion bash >> ~/.bashrc # 生成 fish 补全并立即生效 QOwnNotes --completion fish | source

加密笔记解密：--decrypt-note 与 --decrypt-note-password

--decrypt-note <file>可以把加密笔记文件的解密文本直接打印到命令行并退出。若未提供密码，QOwnNotes 会在命令行中交互式询问密码：

QOwnNotes --decrypt-note secret.md

也可以直接用--decrypt-note-password提供密码：

QOwnNotes --decrypt-note secret.md --decrypt-note-password "my password"

底层实现原理

该功能的完整流程实现在 src/main.cpp 的printDecryptedNoteFile()中：

1. 读取指定文件，构造Note对象并检查hasEncryptedNoteText()；若文件并非加密笔记，则报错退出。
2. 未提供密码时进入交互模式：Windows 平台用_getch()逐字符读取并回显*；POSIX 平台则用termios关闭ECHO | ICANON后逐字符读取，同样以星号回显，回车结束并恢复终端设置（见 src/main.cpp）。
3. 调用note.setCryptoPassword()与canDecryptNoteText()校验密码；失败则提示"密码可能错误"。
4. 通过note.fetchDecryptedNoteText()取得明文，fwrite输出到 stdout（见 src/main.cpp）。相关加密判定与解密方法定义于 src/entities/note.cpp。

::: warning 将密码作为命令行参数传入，密码会暴露在 shell 历史记录或进程列表中。在意这一点时，请优先使用交互式密码提示。 :::

借助管道可以把解密结果直接交给其他命令处理，例如统计字数或转存明文：

QOwnNotes --decrypt-note secret.md | wc -w QOwnNotes --decrypt-note secret.md > secret.txt

启动后触发菜单动作：--action

--action <name>可以在应用启动完成后触发某个菜单动作。例如打开"任务管理列表"对话框：

QOwnNotes --action actionShow_Todo_List

actionShow_Todo_List就是主窗口菜单栏中"任务列表"动作的 objectName，定义于 src/mainwindow.ui，并在工具栏等位置被引用（见 src/mainwindow.ui 与 src/mainwindow.ui）。

::: tip 菜单动作的 objectName 可以在 src/mainwindow.ui 中查询——直接搜索英文菜单标题即可。注意这些文本可能随版本迭代而变化。 :::

触发自定义脚本动作

要触发脚本自定义动作，则在customAction_前缀后拼接自定义动作的标识符，该标识符即脚本调用script.registerCustomAction时的第一个参数（registerCustomAction(identifier, menuText, ...)，参见 webpage/src/scripting/methods-and-objects.md 与示例脚本 docs/scripting/examples/custom-actions.qml）。

例如执行标识符为myAction的自定义动作：

QOwnNotes --action customAction_myAction

底层实现原理

--action的完整动作链路贯穿启动全程：

1. main()手工扫描参数时把动作名存入action变量，最终通过setAppProperties()写入应用属性startupAction（见 src/main.cpp 与 src/main.cpp）。
2. 主窗口构造时调用triggerStartupMenuAction()（见 src/mainwindow.cpp），其实现（src/mainwindow.cpp）读取startupAction属性，通过findAction()在菜单栏的所有菜单中按 objectName 查找动作，再用QTimer::singleShot(0, ...)延迟触发；找不到时弹出 "Action not found!" 警告。
3. findAction()遍历menuList()中每个菜单的全部QAction，逐一比对 objectName（见 src/mainwindow.cpp）。
4. 自定义动作的注册代码将 objectName 设置为"customAction_" + identifier（见 src/mainwindow.cpp），与 CLI 前缀规则完全对应。

单实例模式下的动作转发

::: tip 当 QOwnNotes 设置了"仅允许一个实例"、又用--action连续启动两次时，第二次启动的菜单动作会在第一个实例中触发：第二实例作为SingleApplication的 secondary 实例，会把动作封装为startupAction:<name>消息发送给主实例（见 src/main.cpp），主实例在receivedMessage信号中解析消息并再次调用triggerStartupMenuAction()（见 src/main.cpp）。 :::

利用这一特性，可以在不中断当前编辑状态的前提下，从终端或脚本向正在运行的 QOwnNotes 实例发送指令，例如唤起特定对话框或执行自定义脚本动作。

实战组合示例

把参数组合起来，可以完成不少自动化任务：

# 用隔离会话启动便携版，适合 U 盘或临时环境 QOwnNotes --portable --session usb # 排查安装问题：临时新配置 + 导出诊断信息 QOwnNotes --session test --dump-settings > debug-info.md # 一键生成 bash 补全并立即生效 eval "$(QOwnNotes --completion bash)" # 解密笔记并转存为明文文件（注意密码会出现在进程列表中） QOwnNotes --decrypt-note secret.md --decrypt-note-password "my password" > secret.txt # 向已运行的实例发送"打开待办列表"指令 QOwnNotes --action actionShow_Todo_List

小结

QOwnNotes 的命令行参数覆盖了四大类场景：运行模式（--portable、--session、--allow-multiple-instances）、设置管理（--clear-settings、--dump-settings）、自动化辅助（--completion、--action）与安全工具（--decrypt-note、--decrypt-note-password）。所有参数的注册与处理逻辑集中在 src/main.cpp 的mainStartupMisc()与main()中；shell 补全脚本生成位于 src/utils/cli.cpp；菜单动作的查找与触发实现在 src/mainwindow.cpp。掌握了这些参数，你既可以快速排查安装与配置问题，也能把 QOwnNotes 深度接入自己的脚本工作流。

• 桌面应用