SumatraPDF 命令行参数完全指南：启动、导航、打印与自动化实战

SumatraPDF 命令行参数完全指南：启动、导航、打印与自动化实战

【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdf

SumatraPDF 是一款开源 Windows PDF 阅读器，其命令行接口功能强大：不仅支持打开文档时同时指定页码、缩放、视图模式与搜索词，还内置了面向无人值守场景的完整打印管线、DDE 控制通道以及 LaTeX 正反向搜索支持。本文以官方文档 Command-line-arguments.md 为核心骨架，结合仓库源码与配套文档，系统讲解 SumatraPDF 全部命令行选项的用法、底层实现与自动化技巧，帮助你把它嵌入脚本、编辑器与 kiosk 场景。

说明：本文所述版本信息以当前仓库为准；命令行打印等能力与 Windows 平台强相关，且部分选项（如-dbg-control）依赖特定构建（如 profile 构建）或测试框架。

命令行语法基础

SumatraPDF 的通用调用形式为：

SumatraPDF [argument ...] [filepath ...]

要点如下：

• 大多数选项以连字符-开头；同时也兼容部分 Adobe Reader 的斜杠形式（/p、/t、/A）。
• 部分选项后面会跟随附加参数。
• 未被识别为已知选项的任何内容都被当作文件路径处理，因此可以自由混合文件路径与命令行选项，例如：

SumatraPDF -presentation report.pdf

从源码看，选项的注册表定义在 src/Flags.cpp 的Arg枚举与gArgNames字符串表中，解析逻辑位于ParseFlags()（src/Flags.cpp）。GetArg()会将每个以-//开头的参数去前缀后与字符串表做大小写不敏感匹配，未命中即进入CollectFile分支收集为文件路径（src/Flags.cpp）；解析结果统一存入 src/Flags.h 的Flags结构体，供后续启动流程消费。

一个实用细节：如果某个文件名恰好以-开头（例如-notes.pdf），由于它匹配不到任何已知选项，也会被当作文件处理，但此时该选项之后不能再跟参数，否则参数会被吞掉。

启动方式选项

与源码的对应关系

以上选项在 src/Flags.cpp 中都有直接的处理分支。例如：

• -restrict设置i.restrictedUse = true；
• -presentation/-fullscreen分别设置enterPresentation/enterFullScreen；
• -new-window与-new-window-tabs写入inNewWindow/inNewWindowTabs；
• -appdata写入appdataDir，控制SumatraPDF-settings.txt与缩略图缓存的落盘位置；
• -for-testing写入forTesting，其语义（新实例、不恢复会话、不保存设置）在 src/Flags.h 中有完整注释。

受限模式（kiosk）

-restrict搭配同目录下的sumatrapdfrestrict.ini使用（仓库根目录即提供了一份参考配置 sumatrapdfrestrict.ini）。受限模式下会禁用：打开新文件、从 PDF 内启动 URL、文本/图片选择、打印、更改默认设置、保存到磁盘、自动/手动更新检查、最近文件历史、TeX 预览支持、注册为默认 PDF 阅读器、用 Adobe Acrobat 打开、邮件发送 PDF 等能力。完整选项说明见 Configure for restricted use。

导航选项

以下选项均作用于命令行中的第一个文件；若文档已经打开，可配合-reuse-instance让已有实例响应。

-view可用视图模式

"single page" "continuous single page" facing "continuous facing" "book view" "continuous book view"

含空格的选项值必须用双引号括起来。

-zoom可选值

支持"fit page"、"fit width"、"fit height"、"fit content"，或任意百分比数值（如125、75）。

从源码看，ParseViewMode()通过DisplayModeFromString()将字符串映射为DisplayMode（src/Flags.cpp），ParseZoomValue()则接受fit page/fit width/fit height/fit content的多种连写变体（fitpage、fit-width等），百分比数值会被解析为float，小于 1 的值回退为实际大小（src/Flags.cpp）。

Adobe Reader 兼容的/A参数

/A "<params>"的params是由;、#或&分隔的name=value列表，目前识别：

• page=<n>：跳转到第 n 页（从 1 开始）
• nameddest=<name>：跳转到命名目标
• search=<term>：开始搜索（同-search）

例如：

SumatraPDF /A "page=1;search=mr Fox" file.pdf

同样的name=value列表也可以附加在文件路径的?之后，例如：

file.pdf?page=4;search=foo

这一机制的底层实现是ParseFileArgs()：它把?之后的部分提取出来，交由ParseAdobeFlags()解析（src/Flags.cpp）。ParseAdobeFlags()还额外支持 Sumatra 自定义的annotatt=<n>（附件型注释的 PDF 对象号）与attachno=<n>（附件编号）参数，这些字段定义在 src/Flags.h 的FileArgs结构体中。

通过 DDE 控制已运行实例

-dde cmd发送 DDE 命令（3.5+）

SumatraPDF -dde '[Open("C:\Users\kjk\foo.pdf")]'

• 向当前正在运行的实例发送 DDE 命令。
• 参数必须正确加引号；文件路径必须是绝对路径。
• DDE 命令的通用格式为[Command(parameter1, parameter2, ..., )]，多个命令可拼接为[Command1(...)][Command2(...)][...]。

-dde在源码中的处理见 src/Flags.cpp，命令字符串存入Flags::dde后由启动流程转发给已注册为 DDE 服务器的实例。DDE 服务器名称为SUMATRA、主题为control，Windows API 调用示例见 src/base/Win.cpp 的DDEExecute()。

常用 DDE 命令速览（详见 DDE-Commands.md）

• 打开文件：[Open("<filePath>"[,<newWindow>,<focus>,<forceRefresh>])]
• 正反向搜索（TeX）：[ForwardSearch(["<pdffilepath>",]"<sourcefilepath>",<line>,<column>[,<newwindow>,<setfocus>])]
• 跳转命名目标：[GotoNamedDest("<pdffilepath>","<destination name>")]
• 跳转页面：[GotoPage("<pdffilepath>",<page number>)]
• 搜索：[Search("<pdffilepath>","<search-term>")]（跨页继续并回绕）
• 定位页内词条（3.7+）：[GotoPageWord("<pdffilepath>",<page number>,"<search-term>")]（仅当该词出现在指定页时选中）
• 设置视图：[SetView("<pdffilepath>","<view mode>",<zoom level>[,<scrollX>,<scrollY>])]，其中 zoom 为 8～6400 的百分比，或 -1（Fit Page）、-2（Fit Width）、-3（Fit Content）、-6（Fit Height），0 表示保持当前缩放
• 查询文档状态（DDE request）：[GetFileState("<pdffilepath>")]返回path/page/pageCount/zoom/view/sumver键值对
• 列出打开文件：[GetOpenFiles()]每行返回一个打开文档的完整路径

DDE 命令中字符串里的"与\需要用\转义，例如[SetView(\"c:\\file.pdf\",\"continuous\",-3)]。DDE 方式也是 SumatraPDF 作为 LaTeX 编辑器预览工具的主要集成途径，详见 LaTeX-integration.md。

命令行打印选项

完整的打印指南（含常见任务示例）见 Printing.md。命令行打印的核心选项如下：

-print-settings的底层处理在 src/Flags.cpp：会先去掉字符串中的空格，并把分号;统一转换为逗号,再存储，因此两种分隔符都可以使用。

-print-settings详细说明

设置列表是逗号分隔的页面范围与高级选项组合：

页面范围

• 单页：5
• 范围：2-6，也可反向：10-8
• last：最后一页
• 负数表示从末尾倒数：-1是最后一页，-2是倒数第二页；范围也可用负数，如-3--1表示最后 3 页

输出选项

• even或odd：只打印偶数页或奇数页
• portrait或landscape：提供内容的 90 度旋转（不是纸张旋转，纸张方向必须在打印机默认设置中预先设定）
• disable-auto-rotation：默认情况下，宽大于高的页面会被旋转 90 度以适配纸张；此选项按原始方向打印（3.5 起可用）
• rotate=<degrees>：在自动旋转的基础上额外旋转90、180或270度。适合修正错误方向，例如虚拟打印机上上下颠倒（rotate=180）的输出
• noscale、shrink、fit、stretch：缩放策略，其中stretch在两个维度都填满纸张（忽略宽高比）
• center：将页面在纸张上水平居中。配合noscale在页面小于纸张时有用（例如信封或 A5 纸料送入居中的纸盒）
• color或monochrome
• collate或nocollate：多份打印时是否逐份排序（1,2,3,1,2,3）或不排序（1,1,2,2,3,3）
• duplex、duplexshort、duplexlong、simplex：双面/单面打印
• bin=<num or name>：选择进纸盒。bin=auto让打印机自动选择纸张尺寸与文档页面匹配的进纸盒（类似 Adobe 的 "Choose paper source by PDF page size"）
• paper=<page size>：纸张尺寸为A2、A3、A4、A5、A6、letter、legal、tabloid、statement，或打印机报告的名称（如A3 297 x 420 mm）。自定义尺寸：paper=76mm x 130mm。混合页面尺寸的文档可用paper=auto按每页自身尺寸设置纸张（配合bin=auto同时选择匹配的纸盒）
• paperkind=<num>：按 WindowsDMPAPER_*ID 指定纸张（值可从SumatraPDF.exe -list-printers获取）；当paper=A3无法匹配驱动程序的纸张名称时使用
• ignore-pdf-print-settings：不应用 PDF 内嵌的ViewerPreferences打印默认值（见下文）

使用示例

SumatraPDF -print-to-default -print-settings "1-3,5,10-8,odd,fit,bin=2" file.pdf

该命令打印第 1、3、5、9 页（即范围 1-3、5-5 与 10-8 中的奇数页），并按fit缩放使其适配纸张的可打印区域。

SumatraPDF -print-to-default -print-settings "3x" file.pdf

把文档打印 3 份。

PDF 内嵌打印默认值

对于 PDF 文件，文档ViewerPreferences中内嵌的打印默认值会被自动应用：PrintScaling（/None表示不缩放）、NumCopies、Duplex（Simplex/DuplexFlipShortEdge/DuplexFlipLongEdge）以及PickTrayByPDFSize（按页面尺寸选纸盒）。-print-settings中任何显式设置都会覆盖 PDF 默认值；若想完全忽略 PDF 内嵌值，加上ignore-pdf-print-settings即可。

退出码：无人值守打印的成败判定

使用-print-to/-print-to-default时，进程退出码直接告诉你打印失败的原因，非常适合无人值守/静默打印：

多个文件时，退出码为0当且仅当全部打印成功；否则返回第一次失败所属的类别。注意：作业提交后发生在打印缓冲池/驱动内部的失败（缺纸、脱机等）无法通过此机制报告。

这一设计在源码中有明确注释：PrintResult枚举的数值同时充当进程退出码，以便自动化调用方判断失败原因（见 src/Print.h，对应 issue #3478），主程序在 src/SumatraPDF.cpp 中对每个文件调用PrintFile()并汇总结果。

不支持的 Adobe Reader 标志

以下 Adobe Reader 标志不被支持，因为它们与 SumatraPDF 自身选项冲突：

• /h（在 Adobe 中是帮助，而非隐藏模式）
• /n（在 Adobe 中是 stress-test 并行度，而非新实例）
• /s（在 Adobe 中是静默打印错误，而非抑制启动画面）

LaTeX 正反向搜索相关选项

SumatraPDF 是 LaTeX 工作流中常用的 PDF 预览器，以下选项服务于正向（源码→PDF）与反向（PDF→源码）搜索：

• -forward-search "<sourcepath>" <line> "<pdfpath>"：从 LaTeX 源文件对已加载的 PDF 执行正向搜索（基于 PdfSync 或 SyncTeX），是 ForwardSearch DDE 命令的替代方案。例如：

SumatraPDF -forward-search "/path/to/main.tex" 123 "/path/to/main.pdf"

会高亮 main.tex 中第 123 行对应的所有文本。源码中该选项要求-forward-search（或旧别名-fwdsearch）后紧跟源路径与行号两个参数（src/Flags.cpp），其中AdditionalParam会拒绝任何看起来像选项的参数，避免误吞。

• -reuse-instance：让已打开的 SumatraPDF 实例加载指定文件。若同时有多个运行实例，行为未定义。仅在需要通过 DDE 与 SumatraPDF 通信时才需要（否则请使用ReuseInstance设置）。
• -inverse-search <command-line>：设置从 PDF 执行反向搜索（通常回到 LaTeX 源文件）所用的命令行。也可以在Set Inverse Search Command Line对话框（Ctrl + K命令面板）中设置，或在启用EnableTeXEnhancements后从Settings / Options中设置，或通过高级设置InverseSearchCmdLine设置。命令行中使用%f表示当前文件名、%l表示当前行号。
• -fwdsearch-offset <offset> -fwdsearch-width <width> -fwdsearch-color <hexcolor> -fwdsearch-permanent <flag>：自定义正向搜索高亮。将 offset 设为正数可把高亮样式改为页面左侧的矩形（而不是覆盖所有文本的矩形）。-fwdsearch-permanent的 flag 可为 0（高亮淡出，默认）或 1（持久高亮）。（已弃用）：请改用对应的高级设置。

反向搜索与 SyncTeX 的完整配置流程可参考 LaTeX-integration.md。

开发者与测试选项

-stress-test用法示例

-stress-test file1.pdf 25x -stress-test file2.pdf 1-3 -stress-test dir *.pdf;*.xps 15- 3x

• 第一个示例把 file1.pdf 渲染 25 次；
• 第二个示例只渲染 file2.pdf 的第 1～3 页；
• 第三个示例从目录dir中渲染除前 14 个之外的所有 PDF 和 XPS 文件，每个渲染 3 次。

-stress-test的解析顺序在 src/Flags.cpp 中：路径后先检查含*的文件过滤器，再检查页面范围，最后检查以x结尾的循环次数；页面范围还会经过IsValidPageRange()校验，该函数底层即ParsePageRanges()（src/Flags.cpp），支持3、2-4、5-等写法。

已弃用选项

以下选项只是往设置文件中写入值，可能在未来的任何版本中被移除：

从源码看，这些选项的处理方式是：把参数名与值原样追加到Flags::globalPrefArgs（src/Flags.cpp），之后由设置加载逻辑按旧的键值格式写入设置文件，因此文档明确标注其仅用于兼容、应迁移到高级设置。

组合实战场景

1. 直接打开并定位

SumatraPDF -reuse-instance -page 42 -view "continuous book view" -zoom "fit width" book.pdf

已打开的实例会切到 book.pdf 第 42 页，并应用连续书本视图 + 宽度适配。

2. 无人值守静默打印（结合退出码判断成败）

SumatraPDF -print-to-default -print-settings "1-3,5,10-8,odd,fit,bin=2" -silent report.pdf echo %errorlevel%

3. LaTeX 编辑器正向搜索

SumatraPDF -reuse-instance -forward-search "main.tex" 123 "main.pdf"

4. kiosk 演示机

SumatraPDF -restrict -fullscreen -presentation slides.pdf

配合同目录的sumatrapdfrestrict.ini即可锁住除翻页外的绝大部分操作。

关键文件索引

• 参数定义与解析： src/Flags.cpp、src/Flags.h
• 打印结果/退出码定义： src/Print.h、src/Print.cpp
• DDE 命令文档： DDE-Commands.md
• 受限模式配置： sumatrapdfrestrict.ini、Configure for restricted use
• 完整打印指南： Printing.md
• LaTeX 集成： LaTeX-integration.md
• 安装包命令行参数（/S、/D等，与本文所述运行期参数不同）： Installer-cmd-line-arguments.md

【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdf