Overleaf 匯入 API

​

「Overleaf 匯入 API」功能

從 Ayakaleaf Pro v6.3 開始，您可以建立連結，從 URL 匯入 LaTeX 檔案或壓縮的專案，並在您自己的 Ayakaleaf 執行個體中開啟，類似 Overleaf 的「Open in Overleaf」API。

此功能預設為啟用，您只需造訪 your.overleaf.com/devs 即可查看詳細頁面與說明。

除非設定了 OVERLEAF_ALLOW_PUBLIC_ACCESS=true，否則 /devs 頁面需要登入，請參閱未登入的訪客。

例如，如果您將 LaTeX 檔案託管於 https://example.com/main.tex，或將完整專案託管於 https://example.com/project.zip，就可以建立一個連結，將其匯入您自己的 Ayakaleaf Pro 執行個體並開啟新專案：

LaTeX 檔案

https://ayakaleaf.example.com/docs?snip_uri=https%3A%2F%2Fexample.com%2Fmain.tex

ZIP 專案

https://ayakaleaf.example.com/docs?snip_uri=https%3A%2F%2Fexample.com%2Fproject.zip

請將 ayakaleaf.example.com 替換為您執行個體的網域。

​

在 Ayakaleaf Pro 中開啟 LaTeX 專案

從 Ayakaleaf Pro v6.3 開始，您可以建立連結，將 LaTeX 檔案或壓縮的專案匯入您自己的 Ayakaleaf Pro 執行個體。當有人開啟該連結時，Ayakaleaf Pro 會以所提供的檔案建立新專案，並在編輯器中開啟。

將連結指向您執行個體的 /docs 端點：

參數	說明	範例
snip_uri	要匯入的 LaTeX 檔案 URL。也接受單一 ZIP 檔，但專案請使用 zip_uri。	https://example.com/main.tex
zip_uri	要匯入的壓縮 LaTeX 專案 URL。	https://example.com/project.zip
snip_uri[]	重複此參數即可匯入多個檔案。	snip_uri[]=.../main.tex&snip_uri[]=.../refs.bib
snip_name[]	依相同順序為每個 snip_uri[] 設定檔名。	snip_name[]=main.tex
engine	設定編譯器：latex_dvipdf、pdflatex、xelatex 或 lualatex。	engine=xelatex
main_document	設定匯入專案中的主要 .tex 檔案。	main_document=main.tex
name	設定新專案的名稱。也接受 project_name。	name=My%20Project

例如，如果您的檔案託管於 example.com，這些連結會將它們匯入託管於 ayakaleaf.example.com 的 Ayakaleaf Pro 執行個體。

​

使用 Base64 匯入專案

您可以將 LaTeX 檔案或壓縮的專案以 Base64 data URL 的形式，直接嵌入「Open in Ayakaleaf」連結中。如此一來，您無需將檔案託管於獨立的 URL，即可建立匯入連結。

內容	參數	Data URL 格式
LaTeX 檔案	snip_uri	data:application/x-tex;base64,<base64-encoded-tex>
壓縮的專案	zip_uri	data:application/zip;base64,<base64-encoded-zip>

若要匯入 ZIP 專案，請將 ZIP 檔進行 Base64 編碼，並改透過 zip_uri 傳遞。建構任一種連結時，請對完整的 data URL 使用 encodeURIComponent。對於大型專案，請使用託管的 ZIP URL，因為瀏覽器與伺服器的 URL 長度限制可能會讓 Base64 連結難以實際使用。

​

新增「Open in Ayakaleaf」按鈕

您可以使用 HTML 表單，在訪客點選按鈕時匯入檔案。請以 method="post" 將表單提交至您執行個體的 /docs 端點。

對於託管的 LaTeX 檔案：

<form action="https://ayakaleaf.example.com/docs" method="post" target="_blank">
  <input type="hidden" name="snip_uri" value="https://example.com/main.tex">
  <input type="hidden" name="engine" value="xelatex">
  <button type="submit">Open in Ayakaleaf</button>
</form>

若要匯入壓縮的專案，請將 snip_uri 替換為 zip_uri，並指向 ZIP 檔。您也可以直接提交 LaTeX 原始碼：使用 snip 提交原始文字，或使用 encoded_snip 提交 URL 編碼的文字。

請將 ayakaleaf.example.com 替換為您執行個體的網域。如果您的執行個體啟用了跨來源請求封鎖，請將託管該表單的網站加入 ALLOWED_ORIGINS。

​

未登入的訪客

新專案會建立在訪客的帳號中，因此訪客需要登入。未登入的訪客如何進入取決於匯入的發送方式：

• 連結（GET /docs?...）適用於所有執行個體：訪客會被導向登入頁面，登入後匯入便會繼續進行。
• 表單（POST /docs）需要設定 OVERLEAF_ALLOW_PUBLIC_ACCESS=true 才能供未登入的訪客使用。提交內容會保留 10 分鐘，直到訪客完成登入，且僅會使用一次。

預設情況下（未設定 OVERLEAF_ALLOW_PUBLIC_ACCESS），未登入訪客提交的表單會在 Ayakaleaf Pro 讀取之前就被導向登入頁面，導致提交內容遺失：登入後，訪客會看到 no snippet, snip_uri or zip_uri provided。請改用連結、請訪客先登入，或啟用公開存取，請參閱頁面存取。

我可以匯入哪些 ZIP 或 TeX 資源？

Ayakaleaf Pro 使用 linked-url-proxy 微服務（主要用於 external-url.md）來擷取外部資源。一般而言，任何可透過網際網路公開存取的 ZIP 或 TeX 資源都可以匯入。基於安全考量，託管於私人或內部網路的資源會被封鎖。

從重新發布的 Ayakaleaf Pro 6.3.0（2026 年 10 月 3 日）開始，您可以使用 OVERLEAF_LINKED_URL_OUTBOUND_PROXY 設定 HTTP(S) 代理，用於擷取外部 ZIP 與 TeX 資源。設定方式與網路存取限制請參閱對外代理。