搭建开发环境（本地）

在你的本地服务器或台式机上搭建开发环境。

​

前提条件

Overleaf 是一个典型的微服务架构开源项目，所有服务都运行在 Docker 中。

• 官方 Community Edition 源代码位于 GitHub Overleaf Official。
• Overleaf-CEP 的源代码可在 GitHub Yu-i-i/Overleaf 获取。
• Overleaf Pro Edition 可在 GitHub Ayaka-notes/overleaf-pro 获取。

要搭建 Overleaf 开发环境，你需要一台性能强劲的服务器；建议配置至少 8 核 CPU 和 16GB 内存，因为你需要同时运行 20 多个容器。

由于 8 核及以上 CPU 的服务器通常价格昂贵，强烈建议使用你的本地计算机进行开发。

同时，作为开发者，我们相信你应该已经熟悉 Docker 的安装。我们强烈建议使用较新且稳定的 Ubuntu LTS（例如 2025–2026 年的 Ubuntu 24.04）以及最新版 Docker 进行开发，这样可以减少遇到意外错误的可能性。

总之，你需要：

• 一台用于开发的高性能服务器/台式机
• 较新且稳定的 Ubuntu LTS（例如 Ubuntu 24.04）
• Docker 和 Git 环境

​

配置教程

这里我们以 overleaf-cep 为例，演示如何配置 Overleaf 开发环境。

1. 拉取源代码

   首先，克隆仓库：

   bash

   git clone https://github.com/ayaka-notes/overleaf-pro.git
   cd overleaf-pro
   
2. 同步 package-lock.json

   由于 Overleaf 是在一个内部仓库中开发的，package-lock.json 文件很可能因某些开发问题而不同步。我们需要运行以下命令来同步它（如果你本地有 nodejs 环境）：

   bash

   npm install --package-lock-only --ignore-scripts
   

   如果你没有安装 nodejs，不用担心，可以直接使用 docker 运行相同的命令。在 Overleaf 仓库根目录下运行：

   bash

   docker run --rm \
     -v "$(pwd)":/workspace \
     -w /workspace \
     node:22.18.0 \
     npm install --package-lock-only --ignore-scripts
   
3. 构建开发镜像

   Overleaf 提供了一个专门的目录 /develop 用于存放开发脚本。只需构建各个服务：

   bash

   cd ./develop
   bin/build
   

   如果 Docker 在并行构建服务时内存不足，请在该目录中创建一个包含 COMPOSE_PARALLEL_LIMIT=1 的 .env 文件。

4. 启动所有微服务

   然后启动服务：

   bash

   bin/up
   

   服务运行后，打开 http://localhost/launchpad 创建第一个管理员账户。

   你必须在运行 bin/dev 命令之前运行 bin/up，否则可能会遇到一系列权限问题。

默认情况下，管理员权限不可用。你需要在 develop/dev.env 中添加以下内容，之后即可访问管理面板。

ADMIN_PRIVILEGE_AVAILABLE=true

​

TeX Live

编译 PDF 需要构建一个 TeX Live 镜像，以便在 Docker 内部处理编译：

docker build texlive -t texlive-full

如果要在 macOS 主机上编译，你可能需要在该目录中创建一个包含 DOCKER_SOCKET_PATH=/var/run/docker.sock.raw 的 .env 文件，以覆盖 Docker socket 的路径。

此外，也欢迎使用 ayaka-notes/texlive-full，你可以使用 base 标签，它是 texlive 的最小版本。

​

开发

为了避免每次修改代码后都要运行 bin/build && bin/up，你可以在 开发模式 下运行 Overleaf Community Edition，此时服务会在代码变更时自动更新。

为此，请使用附带的 bin/dev 脚本：

bin/dev

这将使用 node --watch 启动所有服务，它会自动监控代码并在必要时重启服务。

为了提升性能，你可以向 bin/dev 脚本传入以空格分隔的服务列表，只以开发模式启动部分服务：

bin/dev [service1] [service2] ... [serviceN]

以 开发模式 启动 web 服务时，只会在后端代码变更时更新 web 服务。若要同时自动更新前端代码，请确保也以 开发模式 启动 webpack 服务。

如果未指定任何服务，所有服务都将以开发模式启动。

​

调试

在 开发模式 下运行时，大多数服务都会暴露一个调试端口，你可以将调试器（例如 Chrome 开发者工具中的检查器或 IDE 中集成的调试器）附加到该端口。下表列出了每个服务在宿主机上暴露的端口：

服务	端口
web	9229
clsi	9230
chat	9231
contacts	9232
docstore	9233
document-updater	9234
filestore	9235
notifications	9236
real-time	9237
references	9238
history-v1	9239
project-history	9240
linked-url-proxy	9241

要使用 Chrome 的 远程调试 附加到某个服务，请访问 chrome://inspect/ 并确保勾选了 Discover network targets。然后点击 Configure…，为每个你想附加调试器的服务添加一个 localhost:[service port] 条目。

添加条目后，该服务将显示为一个 Remote Target，你可以对其进行检查和调试。

​

日志

在开发环境中，Overleaf 提供了一个 bin/logs 脚本，但你需要安装一些依赖：

sudo npm install -g bunyan
# Or sudo apt install node-bunyan 

或者，你也可以直接运行：

docker compose logs -f [service name]

​

其他工具

完成以上所有步骤后，你可以参考下一节，为你的 Overleaf 开发添加一些调试工具。