> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 搭建开发环境（本地）

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

## 前提条件

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

* 官方 Community Edition 源代码位于 [GitHub Overleaf Official](https://github.com/overleaf/overleaf/tree)。 
* Overleaf-CEP 的源代码可在 [GitHub Yu-i-i/Overleaf](https://github.com/yu-i-i/overleaf-cep) 获取。
* Overleaf Pro Edition 可在 [GitHub Ayaka-notes/overleaf-pro](https://github.com/ayaka-notes/overleaf-pro) 获取。

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

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

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

总之，你需要：

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

## 配置教程

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

<Steps>
  <Step title="拉取源代码">
    首先，克隆仓库：

    ```bash title="bash" theme={null}
    git clone https://github.com/ayaka-notes/overleaf-pro.git
    cd overleaf-pro
    ```
  </Step>

  <Step title="同步 `package-lock.json`">
    由于 Overleaf 是在一个[内部仓库](http://github.com/overleaf/internal)中开发的，`package-lock.json` 文件很可能因某些开发问题而不同步。我们需要运行以下命令来同步它（如果你本地有 nodejs 环境）：

    ```bash title="bash" theme={null}
    npm install --package-lock-only --ignore-scripts
    ```

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

    ```bash title="bash" theme={null}
    docker run --rm \
      -v "$(pwd)":/workspace \
      -w /workspace \
      node:22.18.0 \
      npm install --package-lock-only --ignore-scripts
    ```
  </Step>

  <Step title="构建开发镜像">
    Overleaf 提供了一个专门的目录 `/develop` 用于存放开发脚本。只需构建各个服务：

    ```bash title="bash" theme={null}
    cd ./develop
    bin/build
    ```

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

  <Step title="启动所有微服务">
    然后启动服务：

    ```bash title="bash" theme={null}
    bin/up
    ```

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

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

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

  ```text theme={null}
  ADMIN_PRIVILEGE_AVAILABLE=true
  ```
</Info>

### TeX Live

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

```text theme={null}
docker build texlive -t texlive-full
```

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

此外，也欢迎使用 [ayaka-notes/texlive-full](https://github.com/ayaka-notes/texlive-full)，你可以使用 base 标签，它是 texlive 的最小版本。

### 开发

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

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

```text theme={null}
bin/dev
```

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

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

```text theme={null}
bin/dev [service1] [service2] ... [serviceN]
```

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

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

### 调试

在 *开发模式* 下运行时，大多数服务都会暴露一个调试端口，你可以将调试器（例如 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` 脚本，但你需要安装一些依赖：

```bash theme={null}
sudo npm install -g bunyan
# Or sudo apt install node-bunyan 
```

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

```text theme={null}
docker compose logs -f [service name]
```

### 其他工具

完成以上所有步骤后，你可以参考[下一节](/zh-CN/dev/environment/setup-develop-tools)，为你的 Overleaf 开发添加一些调试工具。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.