設定開發環境（本機）

在您的本機伺服器或桌上型電腦上設定開發環境。

​

先決條件

Overleaf 是典型採用微服務架構的開源專案，所有服務都在 Docker 中執行。

• 官方 Community Edition 原始碼位於 GitHub Overleaf Official。
• Overleaf-CEP 的原始碼可在 GitHub Yu-i-i/Overleaf 取得。
• Overleaf Pro Edition 可在 GitHub Ayaka-notes/overleaf-pro 取得。

要建立 Overleaf 開發環境，您需要一台效能強大的伺服器；建議至少具備 8 核心與 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/up，再執行 bin/dev 指令。否則可能會遇到一連串權限問題。

預設情況下無法使用管理員權限。您需要將以下內容加入 develop/dev.env。之後，您就能存取管理面板。

ADMIN_PRIVILEGE_AVAILABLE=true

​

TeX Live

編譯 PDF 需要建置 TeX Live 映像檔，以在 Docker 內處理編譯：

docker build texlive -t texlive-full

若要在 macOS 主機上編譯，您可能需要在此目錄中建立 .env 檔案並加入 DOCKER_SOCKET_PATH=/var/run/docker.sock.raw，以覆寫 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 開發環境加入一些偵錯工具。