基于 Swift + SwiftUI + 原生 PDFKit 开发的轻量级 macOS PDF 阅读器。
专注纯粹阅读体验,仅保留放大缩小、多窗口对比、多屏/自适应分屏、目录大纲、随输随搜与页码跳转等核心高频功能。
- 纯净无打扰默认界面:启动后进入单屏无侧边栏的空白状态,窗口里不会自动打开任何文件 —— 打开什么完全由你自己决定;打开 PDF 后同样默认进入单屏无侧边栏模式,将 100% 窗口面积留给文档正文;侧边栏仅在点击左上角「侧栏」按钮时按需展开;展开时窗口会按侧栏宽度自动加宽,页面显示区宽度保持不变,不会因此出现横向滚动条。
- 打开即整页(窗口贴合第一页):无论从 Finder 双击、拖到 Dock、工具栏「打开」还是菜单打开,窗口都会自动调整到视口宽高正好等于第一页在
100%下的宽高(工具栏与滚动条额外占位,不算进视口),不留顶部白边、不露出第二页、不出横向滚动条。窗口保持左上角位置,并自动夹在屏幕可见区域内(大幅面 PDF 无法整页放下时以屏幕为准)。 - 精准缩放与档位菜单:放大镜与缩小镜之间是缩放菜单,标签实时显示当前比例(捏合、
⌘滚轮、⌘=/⌘-都会同步)。菜单提供25% / 50% / 75% / 100% / 125% / 150% / 175% / 200%八个固定档位(当前值带勾)、「自适应(窗口宽度)」与「自定义…」(输入10–1000即为10%–1000%,无需输入%)。文档区还支持⌘+ 滚轮 /⌘+ 双指滑动以光标位置为锚点缩放(光标下的内容保持不动,松手后的惯性不再继续放大)。 - 一级分屏菜单(单屏 / 双屏 / 三屏 / 四屏 / 自适应分屏):
- 单屏 / 双屏 / 三屏 / 四屏(2×2 网格):支持同一个 PDF 的多屏跨页对照阅读(如左屏看正文、右屏看图表或参考文献),也支持在副屏点击「换文件」独立打开另一份对比 PDF,或开启「多屏联动顺延翻页」。
- 自适应分屏(按缩放等级智能判断):开启后可根据当前缩放比例自动切换布局——放大(
≥ 115%)自动切为单屏单页精读、中等缩放(72% ~ 114%)自动切为双屏对照、缩小(< 72%)自动切为三屏双页概览,并提供 3 种细分策略可选。 - 五个模式都是同一级的平级项(没有「分屏模式 >」这类子菜单),当前模式带勾;自适应策略与多屏联动仅在对应场景下出现。
- 目录大纲与快速页码导航:自动递归解析 PDF 内置多级
PDFOutline树并展示对应页码,点击即跳;若 PDF 未包含内置目录大纲,自动降级生成全文档快速页码列表。 - 随输随搜(实时全文检索):在搜索框输入字符时自动触发
80ms轻量防抖实时检索,即时高亮全文档匹配项并定位至首处匹配;在搜索框内按回车键(Return)直接循环跳转下一处匹配;当输入变为0匹配时自动彻底清除页面高亮图层。 - 三档响应式自适应工具栏:窗口最小宽度低至
400pt,工具栏按窗口内容宽度自动切换档位——≥ 760pt完整模式(含内联搜索框)、≥ 590pt保留「侧栏 / 打开」文字但搜索收成按钮、< 540pt图标化并可用第二行抽屉搜索。断点由窗口宽度驱动(而不是工具栏自身宽度),因此把窗口缩窄贴在屏幕一侧伴读时不会出现按钮溢出或裁切;打开 A4 文档时窗口约610pt宽,仍处于保留文字的那一档。 - 一键设为系统默认阅读器:在系统顶部菜单栏「SimplePDFReader → 设为默认 PDF 阅读器…」中即可一键绑定为系统默认
.pdf打开应用。初次启动时还会弹出一个「首次运行 app 初始化」面板,一次问清两件事(见下条)。 - 首次运行初始化面板(仅一次):初次安装、第一个窗口就绪后弹出「首次运行 app 初始化」面板——左右并列两个问题框:左框「是否设为默认 PDF 阅读器?」(设为默认 / 以后再说),右框「习惯使用哪种窗口模式?」(多窗口模式 / 单窗口模式)。每个选项是一张圆角矩形卡片(不是按钮),选中后带一圈主题色描边以示区分。底部「我选好了,确认」按钮在两框都选定前灰色不可按,都选定后才变为可按的主操作样式。确认后静默生效(设为默认不再弹二次确认框),并写入「已问过」标记,之后不再打扰;中途退出应用则下次启动重新询问。右上角另有系统标准关闭按钮:点它 = 两项都不选,按程序默认值执行(不设为默认、多窗口模式),同样写入标记、以后不再弹出。面板与应用内所有弹窗、面板均统一相对主窗口居中。
- 重置应用(本地测试利器):菜单栏「SimplePDFReader → 重置应用…」,开着任意多个 PDF 都能执行。确认后立即清除本应用的本地设置(一次确认弹窗即完成,不再弹二次结果提示):首次运行的初始化记录(下次启动重新询问)、窗口模式(恢复默认多窗口)与主窗口框架;当前会话不受影响——关闭并重新打开应用后,就如同首次安装一样。系统层面的默认 PDF 阅读器绑定不受影响。
- 多窗口并行,互不干扰:可同时打开多个窗口(
⌘N新建窗口),把两份文档并排比对,无需多显示器。缩放、翻页、侧边栏、分屏布局、搜索状态全部只作用于当前激活窗口,另一窗口完全不受影响 —— 每个窗口持有独立状态,操作绝不串台。- 打开文件永不顶掉当前内容:从 Finder 双击
.pdf、拖到 Dock 图标、工具栏「打开」按钮、菜单「打开 PDF…」——四处行为完全一致:该文件没开着就按需新开一个窗口放它;已经开着(含作为某个分屏的对比文档)则直接聚焦那个窗口,不重复打开。因此可以一边看 A、一边双击 B 做比对。 - 内容区右上角「关闭本文档」按钮:只关掉本窗口的文档、窗口留着回到空白状态,随时可再拖一份进来;其他窗口完全不受影响。(窗口左上角的系统红点关的才是窗口本身。)
- 打开文件永不顶掉当前内容:从 Finder 双击
- 单窗口 / 多窗口模式:顶部菜单栏新增顶级菜单「窗口模式」(位于「编辑」右侧),下面两项「多窗口 / 单窗口模式」当前生效者带勾,点另一项即切换。两种模式覆盖不同的使用习惯:
- 多窗口模式(默认):即上一条描述的行为 —— 每个还没打开过的 PDF 都会各开一个新窗口,适合并排比对。
- 单窗口模式:全局只保留一个窗口,模仿早期版本的极简行为 —— 无论双击 PDF、工具栏打开还是菜单打开,都只往那唯一的窗口里填(空窗就填入、有内容就替换),绝不新开窗口;此时
⌘N也只是把已有窗口提到最前。 - 从多窗口切到单窗口时会先弹窗确认:「仅保留本窗口,其他窗口关闭并切换到单窗口模式」——由当前窗口发起切换,该窗口会被保留,其余窗口全部关闭;点「取消」则什么都不发生。从单窗口切回多窗口则立即生效、无需确认。模式选择会记忆,下次启动仍然有效。
- 窗口标题实时显示当前模式:空白窗口标题为「SimplePDFReader(多窗口)」,打开文档后为「文件名(多窗口)」;切换模式时所有窗口标题立即同步刷新,与实际模式始终一致。
- 启动即空白,打开什么由你决定:应用启动后永远只呈现一个空白主窗口,不会自动恢复上次打开的文档。想打开什么,双击文件、拖到 Dock、或点工具栏「打开」都可以。
- 应用内署名「关于」面板:菜单栏「SimplePDFReader → 关于 SimplePDFReader」打开应用自绘面板,集中展示应用图标、版本号、作者与仓库链接,并提供「复制仓库地址」与「在 GitHub 上查看」快捷按钮。
下表除「新建窗口」外,所有快捷键都只作用于当前激活窗口;开多个窗口时,不会影响其它窗口。
另外,把
| 功能分类 | 操作说明 | 快捷键 |
|---|---|---|
| 新建窗口 | 新建一个空白窗口(仅多窗口模式;单窗口模式下只是激活已有窗口) | ⌘ + N |
| 打开文件 | 打开 PDF:未打开则新窗口打开,已打开则切到那个窗口,当前窗口空着就地填入(单窗口模式下始终只填那唯一的窗口) | ⌘ + O |
| 关闭本文档 | 关掉本窗口的文档、窗口留着(不关闭窗口,也不影响其他窗口) | ⌥ + ⌘ + W |
| 切换窗口模式 | 在「多窗口 / 单窗口模式」间切换(顶级菜单「窗口模式」,当前生效项带勾,无快捷键) | 菜单「窗口模式」 |
| 视图缩放 | 放大 15% / 缩小 15% |
⌘ + = / ⌘ + - |
| 滚轮缩放 | 以光标位置为锚点放大 / 缩小(触控板双指滑动同样有效,惯性不再继续缩放) | ⌘ + 滚轮 / 双指滑动 |
| 缩放档位菜单 | 选 25% / 50% / 75% / 100% / 125% / 150% / 175% / 200%、自适应(窗口宽度)或自定义 10–1000 |
点击工具栏百分比 |
| 比例重置 | 恢复 100% 原始大小 / 自适应当前窗口宽度 |
⌘ + 0 / ⌘ + 9 |
| 侧边栏开关 | 按需显示或隐藏左侧「大纲 / 搜索」侧边栏 | ⌘ + ⇧ + S |
| 分屏模式切换 | 切换 单屏 / 双屏 / 三屏 / 四屏 / 自适应分屏 | ⌘ + 1 ~ ⌘ + 5 |
| 全文实时搜索 | 聚焦右上角搜索框(输入即实时搜索,回车跳下一项) | ⌘ + F |
| 搜索结果导航 | 查找下一个匹配项 / 查找上一个匹配项 | ⌘ + G / ⌘ + ⇧ + G |
| 页面跳转 | 聚焦页码输入框(输入页码回车跳转) | ⌘ + J |
| 快速翻页 | 上一页 / 下一页 | ⌘ + ↑ / ⌘ + ↓ |
无论选哪条路径,都不需要 Xcode,也不需要命令行工具。 只有想自己改代码的人才需要「方式三」。
- 不想碰终端 → 走「方式一」:浏览器下载,首次打开时去「系统设置 → 隐私与安全性」点一次「仍要打开」。
- 愿意复制粘贴一条命令 → 走「方式二」:零弹窗、零安装,一步到位。
两条路都能正常使用,区别只是你更愿意点一次设置,还是更愿意粘贴一次命令。
三条路径任选其一。「首次打开是否弹窗」与「是否需要装 Xcode」是两个互相独立的代价,别把它们混在一起看:
| 方式 | 需要 Xcode? | 首次打开弹窗 | 适合谁 |
|---|---|---|---|
| 方式一:浏览器下载 Release 产物 | 不需要 | 不想装任何开发工具,能接受点一次「仍要打开」 | |
| 方式二:命令行下载 Release 产物 | 不需要 | ✅ 零弹窗 | 会用终端,想一步到位 |
| 方式三:从源码一键编译 | 需要(约 1–3 GB) | ✅ 零弹窗 | 想自行审计源码或修改代码 |
弹窗到底由什么决定? 由扩展属性
com.apple.quarantine(隔离标记)决定:浏览器下载会自动打上这个标记,curl/git clone不会。 而 Gatekeeper 只在文件带该标记时才会在启动时介入检查 —— 所以「浏览器下载」有弹窗,「命令行下载」和「源码编译」都是零弹窗。 是否需要 Xcode,则只取决于你是「下载现成产物」还是「自己编译」,与弹窗无关。
- 前往仓库右侧 Releases 页面下载最新的
SimplePDFReader-macOS-arm64.zip并解压。架构说明:该产物由 GitHub Actions 在
macos-15(Apple Silicon)运行器上构建,仅支持 Apple Silicon(arm64)机型。Intel Mac 请改用下方的「方式三」从源码编译。 - 将解压出的
SimplePDFReader.app拖入/Applications(应用程序)目录或任意位置双击运行。 - 首次打开安全提示说明:该产物为本地(ad-hoc)签名、未经 Apple 公证。从网络下载后 macOS 会拦截一次,提示「无法打开,因为 Apple 无法检查其是否包含恶意软件」。放行方式有两种(任选其一):
- 系统设置放行:先在 Finder 里双击一次以触发拦截(保持提示框不要关掉),再打开「系统设置 → 隐私与安全性」,向下滚动到「安全性」,点 「仍要打开」,输入登录密码确认。该按钮在被拦截后 1 小时内有效;放行后此 App 会被记为安全性例外,之后可正常双击打开。
- 终端一键解除隔离:在终端执行以下命令清除下载隔离属性后即可直接双击打开:
xattr -cr /Applications/SimplePDFReader.app
⚠️ macOS 15 Sequoia 及更高版本已移除「按住 Control 点击 → 打开」的绕过方式,不要再依赖右键放行。
如果你不介意开一次终端,这是最省事的路径 —— 既不用装 Xcode,也不会出现任何安全弹窗。
首次安装:把下面这一整行复制进「终端」回车即可。
curl -L -o /tmp/app.zip https://github.com/xitihangto/SimplePDFReader/releases/latest/download/SimplePDFReader-macOS-arm64.zip && unzip -oq /tmp/app.zip -d /tmp/app && mv /tmp/app/SimplePDFReader.app /Applications/ && echo "✅ 已安装到「应用程序」"找不到终端?按
⌘ + 空格搜索「终端」,或从「启动台 → 其他 → 终端」打开。
如果已经装过旧版,先执行下面这行移除旧版,再跑上面那条命令(否则新版会被塞进旧版的目录里):
rm -rf /Applications/SimplePDFReader.app等价的分步版本(想知道每一步在做什么可以展开)
# 1. 下载最新版 Release 产物(curl 不会打上隔离标记)
curl -L -o /tmp/SimplePDFReader.zip \
https://github.com/xitihangto/SimplePDFReader/releases/latest/download/SimplePDFReader-macOS-arm64.zip
# 2. 解压
unzip -o /tmp/SimplePDFReader.zip -d /tmp/SimplePDFReader
# 3. 若已安装旧版,先移到废纸篓(避免覆盖时目录嵌套)
mv /Applications/SimplePDFReader.app ~/.Trash/ 2>/dev/null
# 4. 安装到应用程序目录
mv /tmp/SimplePDFReader/SimplePDFReader.app /Applications/原理:curl 不像浏览器那样给文件打上 com.apple.quarantine 属性,因此 Gatekeeper 在启动时不会介入评估,双击即开。
安装后可自查以下两项:
codesign --verify --verbose=2 /Applications/SimplePDFReader.app # 应输出 valid on disk
xattr /Applications/SimplePDFReader.app # 不应出现 com.apple.quarantine已装过旧版,想更新到最新版? 推荐直接跑仓库自带的一键更新脚本(下载最新 CI 产物 → 校验签名 → 旧版移废纸篓 → 装进应用程序目录):
./update.sh # 在仓库目录下执行;也可传具体版本,如 ./update.sh v1.6.0或者手动来:先
rm -rf /Applications/SimplePDFReader.app移除旧版,再跑一次上面的安装命令。不要直接覆盖安装 —— 那样新版会被塞进旧版目录里,出现嵌套。
为什么本机编译不会被 Gatekeeper 拦截? macOS 的「无法验证开发者」弹窗只会出现在带有
com.apple.quarantine(隔离)属性的 App 上, 而这个属性是浏览器和下载工具在保存文件时打上的。 用git clone取得源码并在本机编译,产出的.app天然不带隔离属性, 因此不会触发任何安全弹窗,双击即可运行。
⚠️ 务必使用git clone,不要用网页上的「Download ZIP」按钮。 经浏览器下载的 ZIP 会被打上隔离属性,解压后再编译,产出的.app仍可能弹窗。
# 0. 准备工具链(已装过可跳过)
# 若报 "You have not agreed to the Xcode license agreements",执行:
sudo xcodebuild -license accept
# 1. 克隆源码(不要用 Download ZIP)
git clone https://github.com/xitihangto/SimplePDFReader.git
cd SimplePDFReader
# 2. 一键构建(自动编译 + 本地签名)
chmod +x build_app.sh
./build_app.sh
# 3. 安装到应用程序目录
mv ../SimplePDFReader.app /Applications/脚本会自动完成:用 CoreGraphics 渲染 1024×1024 高清图标并封装 AppIcon.icns → 编译 Swift 源码 → 注入版本号 → 清除扩展属性 → 执行本地(ad-hoc)签名并校验,最后在仓库的上级目录生成 SimplePDFReader.app。
终端输出 构建完成(版本 x.y.z,已本地签名并通过校验) 即为成功。
版本号默认自动读取仓库最近的 git tag;也可以手动指定:
APP_VERSION=1.2.3 ./build_app.sh- 系统:macOS 13.0 或更高,Apple Silicon(arm64)机型(
build_app.sh目前按 arm64 目标编译,Intel Mac 不适用)。 - 工具链:Xcode 或 Xcode Command Line Tools 均可,无需完整 Xcode。
如果目标机器是刚装好系统、没装过任何开发工具的新 Mac,按下面顺序操作。全程不需要 Apple 开发者账号(无需 99 美元/年),也不需要 GitHub 账号(公开仓库可匿名克隆)。
| 顺序 | 操作 | 说明 |
|---|---|---|
| 1 | 确认机型 | 必须 Apple Silicon(M 系列)。「 → 关于本机」查看「芯片」 |
| 2 | 确认系统 | macOS 13.0 或更高 |
| 3 | 安装命令行工具 | 打开「终端」执行 xcode-select --install,在弹窗中点「安装」并同意许可。约 1–3 GB,视网速 5–20 分钟 |
| 4 | 克隆源码 | git clone https://github.com/xitihangto/SimplePDFReader.git |
| 5 | 构建 | cd SimplePDFReader && chmod +x build_app.sh && ./build_app.sh |
| 6 | 安装 | mv ../SimplePDFReader.app /Applications/ |
注意事项:
- 第 3 步之前
git命令是不存在的(git由命令行工具提供)。新 Mac 上直接敲git clone会弹出「安装命令行工具」的提示框——这是最容易卡住的地方,先装好工具链再往下走。 - 若第 5 步报
You have not agreed to the Xcode license agreements,执行sudo xcodebuild -license accept。 - 磁盘预留约 3 GB(命令行工具 + 构建产物)。
- 登录 Apple ID 与构建无关,登不登都可以。
- 不要用浏览器「Download ZIP」下载源码,否则产物会带隔离属性。
- 构建完成后若把
.app通过 AirDrop / 邮件 / 网盘发给别的 Mac,接收方会被重新打上隔离属性并弹窗——这种情况才需要按「方式一」的步骤放行。
关于「能不能一次粘贴执行」:
- 第 3 步必须单独执行,并等待它彻底装完。
xcode-select --install是图形化异步安装——它只负责弹出安装窗口就立刻返回,真正的下载安装(5–20 分钟)在后台进行。如果把它和后面的命令一起粘贴,终端会立刻执行git clone,而此时git尚未安装,必然失败。 - 第 4~6 步可以合并成一条命令,一次粘贴执行(用
&&串联,任一环节失败会自动中断,不会带着错误继续往下跑):
cd ~ && git clone https://github.com/xitihangto/SimplePDFReader.git && cd SimplePDFReader && chmod +x build_app.sh && ./build_app.sh && mv ../SimplePDFReader.app /Applications/ && echo "✅ 已安装到应用程序目录"- 以下几项必须交互,无法自动化:命令行工具安装窗口本身、
sudo xcodebuild -license accept(需要输入登录密码)。
| 现象 | 处理方式 |
|---|---|
You have not agreed to the Xcode license agreements |
执行 sudo xcodebuild -license accept |
xcode-select: error: no developer tools were found |
执行 xcode-select --install |
git: command not found |
命令行工具尚未安装,执行 xcode-select --install |
| 想确认签名是否正确 | codesign --verify --verbose=2 /Applications/SimplePDFReader.app,输出 valid on disk 与 satisfies its Designated Requirement 即正确 |
本项目对外发布的 Release 产物只允许由 GitHub Actions 构建产生,以保证任何一个下载到的 .app 都能溯源到具体的源码提交,杜绝「来源不明的二进制包」。
# 1. 先在 CHANGELOG.md 中新增对应版本的更新段落
# 2. 打 tag 并推送(tag 必须匹配 v* 格式)
git tag v1.0.1
git push --tags
# 3. 等 CI 构建成功、Release 产物就绪后,把本机安装版更新到该产物
./update.sh推送 tag 后,.github/workflows/release.yml 会自动:
- 解析 tag 作为版本号,并通过
APP_VERSION注入到 App 的Info.plist; - 在
macos-15(Apple Silicon)运行器上执行./build_app.sh,从源码编译出SimplePDFReader.app; - 校验代码签名有效,且
Info.plist中的版本号与 tag 一致——任一不通过则构建直接失败,不会产出 Release; - 打包为
SimplePDFReader-macOS-arm64.zip; - 以
CHANGELOG.md作为正文创建同名 Release,并附上该产物。
进入 Actions → Build and Release macOS App → Run workflow,填入要发布的版本号(例如 v1.0.1)即可手动触发一次构建发布。该输入为必填且必须以 v 开头,没有默认值——避免手滑把已发布的 Release 改掉。
- 禁止手工上传本地打包的 zip 作为 Release 附件。本地产物无法自证由仓库源码构建,会破坏产物的可溯源性。
- Release 附件的上传者(uploader)应始终为
github-actions[bot],可据此校验产物真伪。 - 发版前请确认 CI 构建通过;构建失败时不要手工补传产物,应先修复源码或工作流。
- 每次发版后必须更新本机安装版:等 Release 产物就绪后执行
./update.sh,把/Applications/SimplePDFReader.app更新到该产物(下载 → 校验签名 → 旧版移废纸篓 → 安装),保持本机安装版与线上 Release 一致。
SimplePDFReader/
├── Package.swift # Swift Package Manager 配置文件
├── README.md # 项目中文说明文档
├── CHANGELOG.md # 版本更新日志
├── AppIcon.png # 1024×1024 高清应用图标预览
├── AppIcon.icns # macOS 多分辨率原生图标包
├── generate_icon.swift # CoreGraphics 原生矢量图标生成脚本
├── build_app.sh # 一键编译与打包 .app 脚本
├── update.sh # 一键更新 /Applications 里的安装版(下载最新 CI 产物)
├── .github/workflows/release.yml # GitHub Actions 自动构建与发布 Release 工作流
└── Sources/
└── SimplePDFReader/
├── ModelsAndViewModel.swift # 大纲解析、分屏状态、智能缩放策略与实时搜索核心逻辑
├── WindowSupport.swift # 多窗口登记表、窗口管理器、文档共享缓存与应用级设置
└── AppAndViews.swift # PDFKit 视图桥接、响应式工具栏、多屏容器与菜单命令