> ## 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 核心與 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/up`，再執行 `bin/dev` 指令。否則可能會遇到一連串權限問題。
    </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 主機上編譯，您可能需要在此目錄中建立 `.env` 檔案並加入 `DOCKER_SOCKET_PATH=/var/run/docker.sock.raw`，以覆寫 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-TW/dev/environment/setup-develop-tools)，為您的 Overleaf 開發環境加入一些偵錯工具。


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