企业官网建设流程全解析

Overleaf PDF 编译全流程：从 LaTeX 源码到浏览器预览的完整链路

【免费下载链接】overleafA web-based collaborative LaTeX editor项目地址: https://gitcode.com/GitHub_Trending/ov/overleaf

Overleaf 是一个基于 Web 的协作 LaTeX 编辑器，核心体验是点一下 Recompile，左侧.tex源码几秒后就在右侧变成排版好的 PDF。这套「源码→PDF」的能力由一个独立编译服务 CLSI 承担，本文按一次真实编译的流转顺序拆解：请求怎么发出、CLSI 怎么接单、TeX 容器里跑了什么命令、PDF 产物如何落盘再回到浏览器，最后讲报错时先查哪里。所有路径都指向仓库真实源码。

从按钮到 PDF：一次编译的完整链路

先看全景。你把整份项目源码打包发出去，编译服务解析参数、抢下编译锁，在隔离容器里跑latexmk，产物带着一个 buildId 存到本地，浏览器再用 pdf.js 把它画出来。

编译请求怎么发？CLSI 怎么排队接单

前端发出去的是什么

编译入口是 web 服务向 CLSI 发起的POST /project/:project_id/compile，路由注册在 services/clsi/app.js。请求体必须带一个compile对象，参数解析集中在 RequestParser.js：

请求体大小受compileSizeLimit限制，默认 7mb（见 settings.defaults.cjs）。

CLSI 怎么接单

CompileController.js 收到请求后先解析、再交给 CompileManager.js 的doCompileWithLock。每个项目对应一个编译目录compiles/<projectId>；LockManager.acquire(compileDir)对目录加锁，同一项目的并发请求直接返回 423（compile-in-progress），避免多人同时编译互相踩踏。服务最多同时挂compileConcurrencyLimit个编译（普通实例 64、抢占实例 32），HTTP 层超时被放宽到 10.5 分钟，给大文档留出下载与编译的余量。

TeX 容器里跑了什么 LaTeX 命令

拼出来的命令

LatexRunner.js 的_buildLatexCommand负责把参数拼成一条latexmk，核心长这样：

latexmk -cd -jobname=output -auxdir=$COMPILE_DIR -outdir=$COMPILE_DIR \ -synctex=1 -interaction=batchmode -time -f -pdf $COMPILE_DIR/main.tex

引擎由尾部 flag 切换：pdflatex→-pdf、xelatex→-xelatex、lualatex→-lualatex、latex→-pdfdvi，四选一。-synctex=1会额外生成.pdfxref，这正是「点 PDF 跳源码」的基础；开启stopOnFirstError时用-halt-on-error取代-f，遇第一个错误立即退出。

在哪台「机器」上跑

命令不直接落在 CLSI 宿主机，而是交给CommandRunner在 TeX Live 镜像容器里执行（沙箱编译默认镜像quay.io/sharelatex/texlive-full），并用 seccomp / AppArmor 做系统调用隔离。.Rtex、.md等文件会被自动转成.tex再交给 latexmk。开启draft时，DraftModeManager.js 先注入占位内容、跳过图片这类重型元素，让排版快速出一版——测试目录里的 frog.jpg 就是这种草稿模式示例项目用到的图。

PDF 产物落盘在哪、如何回到浏览器

产物落盘

latexmk 跑完后，OutputFileFinder.js 把output.pdf、output.log、output.pdfxref等挑出来，OutputCacheManager.js 再为这次编译分配一个buildId，把整套产物写进output/<projectId>。前端随后可用GET /project/:id/build/:buildId/output/output.zip打包下载，buildId就是区分「第几版 PDF」的凭证。

和 Filestore 的分工

CLSI 只负责「算」，真正的持久化交给独立的 Filestore 服务。CLSI 从 services/filestore/（内部端口 3009）拉取项目源文件、把生成结果写回；FileHandler.js 通过PersistorManager抽象出insertFile/getFile/getRedirectUrl三个动作，底层可对接本地磁盘、GCS、S3。仓库里的 tiny.pdf 是一份只有「Hello World」的最小 PDF，专门用来验证基础链路是否打通。

PDF 预览怎么实现？报错先查哪里

pdf.js 渲染

前端默认用pdfjs作为 PDF 查看器（见 User 模型 中pdfViewer默认值），运行时加载 pdfjs-dist 的pdf.worker把字节流画到画布。web 配置里专门留了 pdfDomain 项，指定客户端从哪个域名去下载编译好的 PDF；编译进行中则通过/project/:id/status接口轮询状态。

报错时先查哪

CompileController把每次编译结果归成几种状态，定位问题时对着它查最快：

想精确到源码行，可结合output.pdfxref与 synctex：GET /project/:id/sync/code由代码定位到 PDF，/sync/pdf反向从 PDF 定位回代码。

整条链路其实就五段接力：web 发请求 → CLSI 解析并抢锁 → TeX 容器跑latexmk→ 产物带 buildId 落盘 → pdf.js 渲染。想深挖任何一段，直接读 services/clsi/、services/filestore/ 与 services/web/ 即可，每个环节都有对应单测兜底。

【免费下载链接】overleafA web-based collaborative LaTeX editor项目地址: https://gitcode.com/GitHub_Trending/ov/overleaf