自建Overleaf本地同步工具：打通云端协作与本地高效编辑

1. 项目概述与核心痛点

如果你和我一样，是个重度 LaTeX 用户，同时又离不开 Overleaf 的云端协作便利性，那你一定也体会过那种“左右为难”的割裂感。在网页编辑器里做最后的排版微调很顺手，但想用本地的 VS Code 或者 Cursor 配合 LSP、代码片段、AI 辅助来写核心章节时，同步就成了大问题。手动下载 zip 包、解压、编辑、再上传，这套流程繁琐得让人完全失去了“本地编辑”的欲望。更头疼的是，Overleaf 项目内部的目录结构（比如main.tex可能藏在某个子文件夹里）和本地你期望的清晰结构往往对不上，时间一长，你自己都搞不清哪个文件对应哪个版本。

这就是Overleaf Local Sync这个非官方工具要解决的核心痛点：它不是一个简单的“双向同步”工具，而是一个映射与桥梁。它的设计哲学很明确：承认并保留 Overleaf 网页端作为“最终呈现和轻量协作”的核心地位，同时为你本地最顺手的编辑器和工作流打开一条清晰、可控、可逆的通道。简单说，它让你在本地有一个永远干净、可读的文件夹，里面的main.tex、chapters/、images/和你硬盘上其他项目没什么两样；而你在这个文件夹里的任何修改，都可以通过一条命令或一个后台监听服务，稳妥地同步回 Overleaf 的对应项目中。

这个项目特别适合自建（Self-Hosted）Overleaf 用户，无论是个人在本地 Docker 跑的服务，还是小团队在内网部署的实例。它通过 CLI、轻量 GUI 和 macOS 原生应用三种方式，把“列项目、绑目录、推拉同步”这些操作变得极其简单。接下来，我会带你从零开始，完整走一遍配置、绑定和深度使用的流程，并分享一些我踩过坑后才总结出的实战经验。

2. 环境准备与项目架构解析

在动手之前，我们得先搞清楚这个工具的“里子”。它不是 Overleaf 的替代品，而是一个精巧的“粘合剂”。理解其架构，能帮你更好地规划工作流和排查问题。

2.1 核心组件与工作原理

项目主要包含两个独立的部分，共享同一套核心逻辑：

1. overleaf-sync/(Node.js 核心): 这是项目的心脏，一个用 Node.js 编写的命令行工具（CLI）。所有与 Overleaf 服务器通信的逻辑——认证、项目列表获取、文件树读取、文件上传/下载——都封装在这里。它通过模拟浏览器会话（使用 Puppeteer）或直接调用 Overleaf 的内部 API 来工作。这也是为什么它需要一个--base-url参数，因为它必须知道你的 Overleaf 实例地址。

2. overleaf-sync-macos-app/(SwiftUI 图形界面): 这是一个为 macOS 用户打造的原生应用。它本质上是一个漂亮的壳，底层调用的仍然是上面那个 Node.js CLI。它的优势在于提供了可视化的项目浏览器、一键绑定、文件状态监控和更友好的设置界面，适合不喜欢敲命令的用户。

3. Tkinter GUI: 位于overleaf-sync/目录下的gui.py，是一个用 Python Tkinter 编写的跨平台简易图形界面。它比 macOS 应用更轻量，适合在 Windows、Linux 或 macOS 上快速测试和简单操作。

同步的基石：.ol-sync.json当你用link命令将一个本地文件夹与一个 Overleaf 项目绑定时，工具会在该文件夹的根目录生成一个名为.ol-sync.json的配置文件。这个文件是一切同步关系的核心，它记录了：

• 目标 Overleaf 实例的基础 URL (baseUrl)
• 目标项目的唯一 ID (projectId)
• 可选的同步忽略规则等

重要提示：这个文件包含了你的项目访问凭证（通过 session 间接关联），务必将其加入你的.gitignore或其它版本控制忽略列表，切勿提交到公开仓库。

2.2 前置条件与安装

假设你已经有一个正在运行的自建 Overleaf 实例（例如通过 Docker Compose 部署在http://localhost:8080）。以下是准备工作的步骤：

1. 获取项目代码：

   git clone https://github.com/AinGerI/Overleaf-Local-Sync.git cd Overleaf-Local-Sync

2. Node.js 环境准备（CLI 必需）: 工具需要 Node.js 环境来运行核心脚本。确保你的系统已安装 Node.js (建议版本 16+)。你可以使用nvm来管理多版本。

   # 检查Node.js版本 node --version # 如果未安装，使用Homebrew (macOS) 或对应包管理器安装 # brew install node

3. Python 环境准备（如需使用 Tkinter GUI）: Tkinter GUI 需要 Python 3。建议使用uv或pip管理虚拟环境。

   # 进入CLI目录 cd overleaf-sync # 使用uv创建虚拟环境并安装依赖（推荐） uv venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows uv pip install -r requirements.txt

4. macOS 应用构建准备: 如果你想使用原生 macOS 应用，需要 Xcode 命令行工具和 Swift 环境。

   cd overleaf-sync-macos-app # 确保有xcode-select xcode-select --install # 运行构建脚本 ./build-app.sh --force # 构建完成后，应用会在 `dist` 目录下 open dist

实操心得：环境隔离是关键我强烈建议为这个项目使用独立的 Python 虚拟环境（uv或venv）和 Node.js 环境。这能避免与系统全局包发生冲突。对于 macOS 应用，如果构建失败，通常是 Swift 包依赖问题，可以尝试先swift package resolve再重新运行构建脚本。

3. 核心工作流详解与实战操作

一切就绪，我们来进入实战环节。我将以最常用的 CLI 方式为例，演示从发现项目到建立稳定同步的完整流程。GUI 的操作逻辑与此完全一致，只是交互形式不同。

3.1 第一步：发现并列出你的 Overleaf 项目

首先，你需要知道你要同步哪个项目。使用projects子命令来列出你 Overleaf 实例中的所有项目。

# 进入核心CLI目录 cd overleaf-sync # 列出项目，将 --base-url 替换为你的Overleaf地址 node ol-sync.mjs projects --base-url http://localhost:8080

第一次运行时会触发认证流程。工具会尝试打开一个浏览器窗口（或使用无头模式）让你登录你的 Overleaf 实例。登录成功后，你的会话信息（通常是 Cookie）会被安全地保存在~/.config/overleaf-sync/session.json文件中，后续操作将复用此会话，无需重复登录。

命令执行成功后，你会看到一个类似下面的列表：

[ { id: '65f2a1b2c3d4e5f678901234', name: 'My Thesis - Chapter 1' }, { id: '65f2a1b2c3d4e5f678901235', name: 'Conference Paper Draft' }, ... ]

请务必记下你想要同步的项目的id，下一步会用到。name字段帮助你识别项目。

注意事项：认证与会话安全session.json文件等同于你的登录凭证。请妥善保管，避免泄露。如果你在公共或共享计算机上使用，建议在使用后删除此文件。工具本身不会将密码存储在任何地方，它存储的是登录后的会话令牌。

3.2 第二步：建立本地与远端的映射关系

这是最关键的一步——链接（Link）。你需要一个本地的空文件夹（或已有内容的文件夹，但需谨慎），将其与 Overleaf 上的特定项目绑定。

# 创建一个本地文件夹（如果尚未存在） mkdir -p ~/Documents/OverleafSync/MyThesis # 执行链接命令 node ol-sync.mjs link \ --base-url http://localhost:8080 \ --project-id 65f2a1b2c3d4e5f678901234 \ --dir ~/Documents/OverleafSync/MyThesis

这个命令会做以下几件事：

1. 验证项目 ID 和会话有效性。
2. 在指定的本地目录 (--dir) 下生成.ol-sync.json配置文件。
3. （可选但推荐）首次将 Overleaf 项目中的文件结构**拉取（Fetch）**到本地目录，为你建立一个清晰的初始状态。这通常通过后续的pull或首次push前的对比来完成，但链接操作本身让你做好了准备。

执行成功后，进入你的本地目录，应该能看到.ol-sync.json文件。现在，这个文件夹就和你 Overleaf 上的那个项目建立了唯一的关联。

3.3 第三步：双向同步的两种模式

绑定完成后，你可以根据工作习惯选择两种同步模式：

模式一：手动推送（Push）—— 适合精细控制当你完成一批本地修改，并确认无误后，手动将更改推送到 Overleaf。

node ol-sync.mjs push --dir ~/Documents/OverleafSync/MyThesis

因为.ol-sync.json里已经记录了base-url和project-id，所以命令可以简化。push操作会：

• 扫描本地目录的文件。
• 与 Overleaf 项目中的文件进行对比。
• 上传本地新增或修改的文件。
• 默认情况下，不会删除 Overleaf 上存在但本地已删除的文件（安全设计）。如果你确信要删除，需要使用--delete-remote标志（慎用）。

模式二：监听模式（Watch）—— 适合流畅的本地编辑体验如果你希望像使用本地文件一样，保存后自动同步，可以启动监听服务。

node ol-sync.mjs watch --dir ~/Documents/OverleafSync/MyThesis

启动后，该终端会保持运行，并监听指定目录内所有文件的更改事件（保存、创建、删除）。一旦检测到变动，它会自动执行一次push操作，将变更上传。这对于在 VS Code 或 Cursor 中持续写作非常方便，实现了“保存即同步”的近似体验。

重要警告：Watch 不是实时协同编辑watch模式只是简化了手动执行push的步骤，它不是Google Docs 那种实时协同。如果同时在网页端和本地修改同一个文件，后保存的一方会覆盖先保存的一方，且没有自动合并冲突的功能。因此，它最适合个人或明确分工（例如，A负责写章节，B负责在网页端调格式）的场景。

3.4 第四步：处理来自网页端的修改

你或者你的合作者在 Overleaf 网页编辑器里做了修改，如何将这些改动安全地同步回本地？使用pull命令。

node ol-sync.mjs pull --dir ~/Documents/OverleafSync/MyThesis

pull操作会：

1. 获取 Overleaf 项目当前的文件树。
2. 与本地文件进行对比。
3. 对于远端有更新而本地未修改的文件，直接更新本地副本。
4. 对于冲突情况（即同一个文件在远端和本地都被修改了），工具会采取保守策略：它不会覆盖你的本地修改，而是将远端版本下载下来，重命名（通常加.remote后缀）后保存在同一目录。例如，main.tex冲突后，你会得到main.tex（你的本地版本）和main.tex.remote（网页端版本）。你需要手动检查并合并它们。
5. 对于远端已删除而本地仍存在的文件，默认不会删除本地文件（同样是安全设计）。

这种“非破坏性”拉取是该项目“安全第一”设计理念的体现，避免了因误操作导致本地工作丢失。

4. 高级配置、技巧与故障排查

掌握了基本工作流后，下面这些进阶知识和技巧能让你用得更顺手，并避开我早期遇到的那些坑。

4.1 同步行为定制与.ol-sync.json详解

.ol-sync.json文件不仅是链接凭证，也可以用来配置同步行为。一个完整的配置可能如下所示：

{ "baseUrl": "http://localhost:8080", "projectId": "65f2a1b2c3d4e5f678901234", "ignore": [ "**/.git/**", "**/node_modules/**", "*.log", "*.aux", "*.out", "_minted-*" ], "strategy": "conservative" }

• ignore: 这是最有用的配置项。你可以使用 glob 模式来指定哪些文件或目录不需要同步。强烈建议将版本控制目录（.git）、LaTeX 编译中间文件（.aux,.log,.out）、以及本地编辑器缓存目录加入忽略列表。这能大幅减少不必要的同步操作和潜在冲突。
• strategy: 同步策略。工具可能支持不同的策略（如conservative（保守，默认）,aggressive（激进）），用于处理删除等危险操作。查阅项目最新文档以获取支持选项。

4.2 图形界面（GUI）的便捷之处

对于不习惯命令行的用户，或者想快速浏览项目状态，GUI 是绝佳选择。

Tkinter GUI 启动:

cd overleaf-sync uv run python gui.py

启动后，一个简单的窗口会出现。你通常需要：

1. 在设置中填入 Overleaf 实例的 Base URL。
2. 点击“Login”或“Refresh Projects”进行认证并拉取项目列表。
3. 从列表中选择项目，并指定一个本地文件夹进行“Link”。
4. 之后，可以通过界面按钮进行“Push”、“Pull”或“Watch”操作。界面会显示简单的操作日志。

macOS 原生应用: 构建并打开应用后，你会获得一个更美观、集成度更高的体验。它通常以侧边栏形式展示项目列表，主窗口显示已链接文件夹的文件状态（如本地清洁、本地有修改、远端有更新等），并提供一键同步按钮。状态可视化能极大提升心智舒适度。

4.3 典型问题与解决方案实录

以下是我在长期使用中遇到的一些典型问题及解决方法：

4.4 与现有 Git 工作流集成

很多人本地已经用 Git 管理 LaTeX 项目。Overleaf Local Sync可以和 Git 完美共存，关键在于.gitignore。

1. 忽略同步元数据：确保你的.gitignore文件包含.ol-sync.json。这个文件包含项目特定信息和潜在会话信息，不应纳入版本控制。
2. 忽略 LaTeX 编译产物：同样，将*.aux,*.log,*.out,*.toc,*.bbl,*.blg,*.synctex.gz等加入.gitignore。这些文件也可以同时加入.ol-sync.json的ignore列表，实现双重过滤。
3. 工作流：你可以自由地在本地文件夹中使用 Git 进行版本管理。当你准备将一组更改推送到 Overleaf 时，先提交到 Git，然后执行ol-sync push。从 Overleaf 拉取更新后，如果有合并冲突，可以利用 Git 的强大合并工具来解决，这比手动处理.remote文件更高效。

5. 设计理念反思与最佳实践建议

经过几个月的深度使用，我对这个工具的设计哲学有了更深的体会，也总结出了一套让协作更顺畅的最佳实践。

5.1 理解其“桥梁”而非“替代”的定位

这是最重要的一点。Overleaf Local Sync没有试图重建一个完整的版本控制系统，也没有实现复杂的 OT 或 CRDT 算法来解决实时冲突。它清醒地认识到 Overleaf 网页端在渲染预览、轻量协作和最终调整上的不可替代性，因此只做自己最擅长的事：建立一条可靠的文件传输通道，并保持本地工作区的整洁。

这种“保守”的设计带来了巨大的好处：简单、可靠、可预测。你不会遇到神秘的文件丢失或无法解析的冲突状态。所有操作都是显式的，所有潜在危险操作（如删除）都需要额外标志。这使得它特别适合学术写作这种容错率低、文件关系复杂的场景。

5.2 个人与小团队协作的最佳实践

基于其定位，我推荐以下工作流来最大化其效益，同时最小化冲突风险：

1. 明确分工与“锁”约定：

   • 章节作者：在本地使用链接的文件夹进行深度写作。使用watch模式或定时push，将草稿持续同步到 Overleaf。
   • 格式调整/合作者：主要在 Overleaf 网页端活动，负责调整格式、检查参考文献、插入评论等。避免在网页端进行大段的文字重写。
   • 约定：当一个人在本地进行重大重构（如重命名章节、移动大量文件）时，提前在团队频道说一声：“我正在本地重构第3章，接下来15分钟请不要在网页端修改任何文件。” 这相当于一个简单的“软锁”。

2. 同步节奏化，而非实时化：

   • 不要追求绝对的实时同步。改为阶段化同步。例如，本地写完一个小节后，执行push；准备开始新工作前，执行一次pull获取最新状态。
   • 每天工作开始和结束时，各做一次完整的pull-> (本地工作) ->push循环。这能确保起止点状态一致。

3. 善用.ol-sync.json的忽略列表：

   • 这是提升体验的关键。把一切生成文件、缓存文件、个人编辑器配置（如.vscode/中的非共享设置）都忽略掉。只同步纯粹的源文件（.tex,.bib,.sty,.cls, 图片文件等）。
   • 一个推荐的忽略列表起步模板：

     "ignore": [ "**/.git/**", "**/.svn/**", "**/.history/**", "**/node_modules/**", "*.log", "*.aux", "*.out", "*.toc", "*.lof", "*.lot", "*.bbl", "*.blg", "*.synctex.gz", "*.fdb_latexmk", "*.fls", "_minted-*/**", "*.pyg" ]

4. 本地备份与版本控制：

   • 工具不能替代备份。务必对你的本地文件夹使用 Git 进行版本控制。每次重要的push到 Overleaf 前后，都做一次 Git 提交。这样，即使 Overleaf 端或同步过程出现问题，你都有完整的本地历史可以回退。
   • 考虑将本地 Git 仓库推送到一个私有远程仓库（如 GitHub Private, GitLab, Gitea），实现异地备份。

5.3 性能与稳定性调优

对于大型项目（数百个文件，特别是大量图片），同步速度可能会变慢。以下是一些优化思路：

• 精简同步范围：通过ignore列表严格过滤，是提升速度最有效的方法。
• 避免watch监听过多文件：如果ignore配置得好，watch需要监听的文件系统事件就少，响应会更灵敏。
• 网络考虑：如果你的自建 Overleaf 在远程服务器上，同步速度受网络影响。对于大文件（如高分辨率图片），可以考虑先压缩，或使用 Overleaf 的图片上传功能而非通过同步工具。
• Session 管理：如果长时间未使用，session.json可能过期。此时工具会提示重新登录。定期清理旧的session.json文件并无害处。

这个工具填补了自建 Overleaf 生态中一个非常具体的空白。它没有过度设计，而是用一组简单的命令和一个清晰的心智模型，解决了本地编辑与云端协作之间最痛的摩擦点。如果你受困于 Overleaf 网页编辑器的局限性，又舍不得其协作和预览的便利，那么把它加入你的工具箱，很可能会显著提升你的 LaTeX 写作体验和效率。它的价值不在于技术上的炫酷，而在于对真实工作流的深刻理解和务实解决。