Windows本地部署Overleaf：解决Docker路径挂载与TeXLive宏包缺失

如果你们组里也有一位每次提交论文前都要在Overleaf上跟模板搏斗的成员或者你只是受够了在公共平台上排长队等编译那在自己电脑上部署一套 Overleaf Community Edition 绝对值得动手。简单来说它就是一个跑在 Docker 容器里的在线 LaTeX 协作编辑器数据和编译全部在本地完成模板想换就换宏包想装就装编译速度由你自己的 CPU 决定再也不用看公共服务器的心情。Windows 下部署整体不复杂但有两个坎几乎所有人都躲不过Docker 路径挂载报错以及默认 TeXLive 宏包太少导致编译失败。这篇文章就围绕这两个核心难点展开顺带把从下载到日常使用的完整流程串一遍。我需要提前声明一下下面这套东西是我自己在 Windows 11 Docker DesktopWSL2 后端上一步步跑通的所用 Toolkit 版本是 2024 年中的版本。不同版本的配置项名称可能会略有差异但排查思路完全通用。1. 部署前必须想明白的几件事1.1 本地 Overleaf 到底解决了什么问题公共 Overleaf 最大的槽点有三个编译排队、文件数量限制、宏包无法自由定制。本地部署之后编译在你自己机器上跑小型项目编译也就几秒钟文件数量限制不再存在宏包缺失可以直接进容器装。相比在别处搭 LaTeX 环境Overleaf Community Edition 保留了网页编辑器这套交互团队成员不需要装任何 TeX 发行版打开浏览器就能改。如果你有写论文、做模板、带团队协作的需求这套东西是相当合适的。我自己是因为要反复改一个期刊模板公共站每次编译排队三分钟实在忍不了才决定本地部署。装完之后最大的感受是本地编译速度确实快模板调试的试错成本低太多了。1.2 一套系统由哪些容器组成Overleaf Community Edition 并不是一个单一程序它是由几个服务容器组成的sharelatex主应用承载 Web 界面和 LaTeX 编译引擎mongo数据库存用户、项目元数据redis缓存filestore文件存储启动时Toolkit 脚本会通过 Docker Compose 编排这些容器。核心的 sharelatex 容器内部集成了一个 TeXLive 环境LaTeX 编译由它完成。理解这一点很重要因为后面谈到的两个问题——路径报错和宏包安装全都是围绕这几个容器的配置展开的。1.3 Windows 环境需要准备的清单在动手之前先把下面这四件事确认好能省掉后面一大半的折腾时间安装 Docker Desktop并且确保后台用的是 WSL2 引擎。可以在 Docker Desktop 的 Settings - General 里勾选 Use the WSL 2 based engine。磁盘空间至少留出 10GB 以上。精简版镜像几百 MB但如果你后面要装全量 TeXLive下载加解压轻松超过 6GB。准备一个纯英文、无空格的目录存放 Toolkit。建议直接用C:\overleaf\toolkit这种路径别放在C:\Users\张三\Desktop\我的文件夹下面否则后面很可能遇到莫名其妙的脚本路径报错。能访问 Docker Hub。拉镜像如果慢提前配置镜像加速器具体做法后面会讲。2. 从下载到跑通完整部署过程2.1 获取 Toolkit 并放到合适位置Overleaf 官方把部署脚本放在 GitHub 上项目名叫 overleaf/toolkit。下载方式很简单git clone https://github.com/overleaf/toolkit.git C:\overleaf\toolkit如果你没装 Git也可以直接到 GitHub 页面下载 ZIP 包再解压。但下载之后一定要记住整个目录的路径不能包含空格和中文文件夹名也不要用overleaf toolkit这种带空格的命名方式。进入目录后你会发现下面有bin、config、lib等文件夹。我们主要操作的是config目录里的overleaf.rc文件。这个文件是 Toolkit 的全局配置所有主要参数都在这里改。2.2 修改配置文件的几个关键项打开config/overleaf.rc你会看到类似这样的内容# The web site address is usually only relevant for email alerts OVERLEAF_HOSTNAMElocalhost # The port that Overleaf will listen on OVERLEAF_PORT80这里比较值得改的是端口。如果你的 80 端口已经被其他程序占用比如我机器上的 IIS 就占着 80把OVERLEAF_PORT改成 8080 或者其他空闲端口就行。如果你希望局域网内其他设备也能访问还需要设置OVERLEAF_LISTEN_IP0.0.0.0默认情况下它只监听本机回环地址改完之后同一局域网下的同事就能通过你的局域网 IP 访问。注意 Windows 防火墙要放行对应端口。除了端口还有几个管理员邮箱之类的设置项可以暂时不填第一次启动时会要求你在网页上初始化管理员账号。2.3 启动容器与初始化管理员接下来就是启动。这里要特别提醒在 Windows 上工作的朋友bin/up是一个 bash 脚本你不能直接在 CMD 或者 PowerShell 里双击运行需要打开 Git Bash 或者在 WSL 终端里执行。如果你完全没装过 Git Bash直接安装 Git for Windows 就能获得一个可用的 bash 环境。在 Git Bash 中进入 Toolkit 目录cd /c/overleaf/toolkit ./bin/up第一次运行会拉取镜像、创建容器整个过程取决于你网速。如果这一步卡住不动大概率是 Docker Hub 拉取镜像太慢解决办法我放在后面问题排查部分。启动成功后浏览器打开http://localhost:8080/launchpad端口改成你自己设置的页面会引导你创建第一个管理员账号。这个账号不是普通用户它拥有管理后台权限建好后就能正常登录使用 Overleaf 了。3. 解决 Docker 路径报错排查思路与处理3.1 路径报错的典型现场Windows 上跑 Docker 容器路径问题可以说是踩坑重灾区。我自己遇到的报错大致分三类下面把报错现象和根因一起列出来报错信息里出现mounts denied这是 Docker Desktop 的 Windows 文件共享权限问题。报错信息里出现invalid mount path: C:\Users\xxx... mount path must begin with /这是路径格式问题Windows 风格反斜杠路径在 Docker Compose 里不被识别。运行./bin/up时提示找不到路径或者文件而路径里明明有内容这多半是 Toolkit 所在目录带空格导致的。这三种情况的处理方式各不相同但排查方向是一致的先判断是“文件共享没开”还是“路径表达式写错”还是“脚本被空格坑了”。3.2 两种最常见的根因第一种根因是 Docker Desktop 没有把 Windows 盘符共享给 WSL2。Docker Desktop 在 WSL2 模式下容器要访问 Windows 文件系统需要你在 Docker Desktop 里显式允许共享对应盘符。处理方法是打开 Docker Desktop进入 Settings - Resources - File Sharing把你项目所在的盘符比如 C 盘或 D 盘添加进去然后点 Apply Restart。第二种根因是路径表达式不兼容。这个问题更容易出现在你自己修改 docker-compose.yml 文件时。比如你写了volumes: - C:\overleaf\toolkit\data:/overleaf/data在 YAML 文件中反斜杠会被转义而且 Docker CLI 根本不认 Windows 路径。正确写法应该改成 Linux 风格路径volumes: - /c/overleaf/toolkit/data:/overleaf/data或者用 Docker Desktop 在 WSL2 下常见的/run/desktop/mnt/host/c/...前缀例如volumes: - /run/desktop/mnt/host/c/overleaf/toolkit/data:/overleaf/data具体用哪种取决于你的 Docker Compose 运行环境。有一个快捷判断方法在 Git Bash 里执行pwd -W看它输出的路径形式然后照着那种形式改。3.3 权限与性能问题路径报错解决之后还有两个容易被忽略的次生问题。第一个是权限错误。Windows NTFS 文件权限在 WSL2 里的映射比较特殊有时候容器内进程对挂载的 Windows 目录只有只读权限报错会显示Permission denied。解决办法比较简单在 Git Bash 中手动 chmod 一下目录权限chmod -R 777 /c/overleaf/toolkit/data需要注意这种粗暴授权方式只适合本地开发环境别放到生产服务器上。第二个问题是性能。Overleaf Toolkit 的数据目录包含大量小文件比如编译缓存、项目文件。这些文件如果直接放在 Windows 文件系统上容器每次读写都要跨文件系统速度会明显变慢。我实测过同样的项目数据目录在 Windows 盘符下编译耗时比在 WSL2 原生文件系统下慢接近一倍。如果项目比较重建议把 Toolkit 的 data 目录放到 WSL2 的~/overleaf-data下然后在 Windows 侧通过\\wsl$访问。不过这个方案对小白不太友好日常使用量不大的话直接放在 Windows 磁盘其实也能接受。4. 全量宏包安装告别“File not found”4.1 宏包缺失的编译报错现场Overleaf 官方镜像默认集成的 TeXLive 是精简版只包含一小部分常用宏包。很多论文模板用到的包比如cventry.sty、siunitx.sty、fontawesome5.sty在精简环境里并不存在。你会在项目编译日志里看到类似这样的一行! LaTeX Error: File xxx.sty not found.在公共 Overleaf 上这种情况已经很少出现因为公共服务器的 TeXLive 是全量安装的。但本地社区版不会自动帮你补齐宏包你需要自己处理。在动手之前先确认一下到底缺哪些包。进入容器执行docker exec -it sharelatex bash kpsewhich siunitx.sty如果kpsewhich返回空说明这个包确实不存在。注意容器名不一定是sharelatex可以用docker ps查看实际名称。4.2 方案一调整 TeXLive 安装方案这是我最推荐的方案适合从头部署或者可以接受重新初始化的场景。较新版本的 Toolkit 支持通过环境变量控制 TeXLive 的安装粒度。你可以在config/overleaf.rc里加上一行SHARELATEX_TEXLIVE_SCHEMEfull然后重新执行./bin/upToolkit 在初始化 TeXLive 时就会按照 full 方案安装完整宏包集合。整个安装过程会下载数 GB 的包耗时和网速强相关。如果你网速一般建议先把 Docker 镜像加速配置好或者给容器配置国内 CTAN 镜像源再执行。需要提醒的是这个配置项在不同版本的 Toolkit 里可能名称不太一样。如果你的overleaf.rc里没有这个变量也可以打开生成后的 docker-compose.yml 查看 sharelatex 服务的 environment 字段看看有没有类似TEXLIVE_SCHEME的键名。以你实际版本中的配置名为准。4.3 方案二容器内补装并持久化如果你的 Overleaf 已经跑起来并且里面有重要项目不想重新初始化那就采用容器内补装的方式。先进入容器docker exec -it sharelatex bash然后安装缺失的宏包tlmgr install siunitx fontawesome5 cventry安装完成后退出容器再重启服务docker restart sharelatex这样操作起来很快但有一个大坑容器可写层在容器删除后会消失。如果你之后执行了./bin/down或者删除了容器这些宏包全部白装又得重新来一遍。要让补装的宏包持久化有两种做法。简单粗暴的方法是补装完成后执行docker commit sharelatex overleaf/sharelatex:with-extra-packages然后把 docker-compose.yml 里 sharelatex 服务的 image 字段改成overleaf/sharelatex:with-extra-packages以后容器重建就是用这个带宏包的新镜像。注意docker commit 做出来的镜像体积巨大而且属于不可追溯的“临时快照”生产环境不建议这么用但个人使用完全没问题。4.4 验证与加速不管用哪种方案装完之后都建议跑一个全量测试。找一个需要较多宏包的模板重新编译一次确认没有任何File not found报错。关于加速这里分享两个实测有效的技巧。技巧一给 Docker 配置镜像加速。在 Docker Desktop 的 Settings - Docker Engine 里修改配置{ registry-mirrors: [ https://docker.mirrors.ustc.edu.cn ] }保存后 Docker 会重启。技巧二给 TeXLive 换国内 CTAN 镜像源。进入容器执行tlmgr option repository https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/tlnet之后再执行tlmgr install速度会有明显提升。5. 高频问题速查与我的避坑经验5.1 常见问题速查表我在部署和后续使用过程中整理了一张问题排查表按踩坑频率排了序方便你对照处理问题现象根因解决方法mounts deniedDocker Desktop 文件共享未开启Settings - Resources - File Sharing 添加对应盘符重启 Dockerinvalid mount pathWindows 路径被写进 Docker Compose改成/c/...或/run/desktop/mnt/host/c/...格式File not found编译报错TeXLive 宏包缺失切换 full 方案或容器内 tlmgr 补装镜像拉取很慢未配置加速器Docker Engine 添加 registry-mirrors./bin/up报路径找不到Toolkit 路径含空格或中文移到纯英文无空格目录重新 clone容器内补装的宏包重启后丢失容器可写层未持久化docker commit 生成新镜像本地编译速度慢数据目录在 Windows 挂载点上把 data 目录放到 WSL2 原生文件系统/launchpad打不开首次初始化未完成或端口未生效查看docker logs sharelatex确认服务就绪后重试5.2 几条真实避坑经验第一条不要在 Windows 上直接用./bin/up反复重启。Toolkit 的启动脚本偶尔会在退出的瞬间没把容器清干净导致下次启动时端口冲突。遇到这种情况可以先执行./bin/down docker compose down -v然后再./bin/up。注意down -v会清掉数据卷如果里面已经有重要项目先把数据目录备份出来。第二条Overleaf 社区版默认没有备份机制。数据库和项目文件都存在 Toolkit 的 data 目录里。我建议每周手动把 data 目录压缩一份到其他位置。别问我为什么强调这一点有一次我升级 Docker Desktop 之后容器全崩数据差点没保住。第三条全量 TeXLive 并不是“所有宏包”的意思。full方案已经涵盖了绝大多数常用宏包但如果你用了非常新的包或者某个期刊提供的私有包依然可能缺失。这时候就得回归 tlmgr 手动补装。换句话说方案一解决的是大多数人缺包的问题但不能百分之百保证任何宏包都存在。第四条Windows 防火墙通常会在第一次启动时弹出提示问你是否允许 Docker 通过防火墙。如果你想让局域网同事访问这里一定要勾选“允许”。如果错过了弹窗去 Windows 安全中心的防火墙设置里手动放行 Docker Desktop 对应端口。5.3 写在最后的个人体会我实际跑下来Overleaf Community Edition 在 Windows 上的部署难度不算高真正花时间的地方就是路径和宏包这两个点。路径问题本质上是 Windows 文件系统与 Linux 容器的“翻译”问题搞清楚它之后你可以举一反三解决以后所有 Docker 挂载目录的问题。宏包问题本质上是一个“镜像精简”问题理解了官方镜像为什么不带全量 TeXLive你自然就明白为什么要换 full 方案以及为什么容器内补装不够持久。最后再分享一个我自己的使用习惯我会把 ToolKit 的config/overleaf.rc和docker-compose.yml两个文件复制一份到自己的 Git 仓库里每次修改配置后提交一次记录。Windows 上部署过一次的人都会明白能在出问题时快速回滚到上个可用配置比什么都重要。希望这篇教程能帮你少走几小时弯路把时间留给真正该做的事——好好写论文。