Overleaf 导入 API

​

“Overleaf 导入 API”功能

从 Ayakaleaf Pro v6.3 开始，你可以创建链接，从某个 URL 导入 LaTeX 文件或 zip 压缩的项目，并在你自己的 Ayakaleaf 实例中打开它，类似于 Overleaf 的 “Open in Overleaf” API。

此功能默认启用，你只需访问 your.overleaf.com/devs 即可查看详细页面和说明。

除非设置了 OVERLEAF_ALLOW_PUBLIC_ACCESS=true，否则访问 /devs 页面需要登录，请参阅未登录访客。

例如，如果你在 https://example.com/main.tex 托管了一个 LaTeX 文件，或在 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 文件或 zip 压缩的项目导入到你自己的 Ayakaleaf Pro 实例中。当有人打开该链接时，Ayakaleaf Pro 会根据所提供的文件创建一个新项目，并在编辑器中打开它。

将链接指向你的实例的 /docs 端点：

参数	描述	示例
snip_uri	要导入的 LaTeX 文件的 URL。也接受单个 ZIP 文件，但对于项目请使用 zip_uri。	https://example.com/main.tex
zip_uri	要导入的 zip 压缩 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 文件或 zip 压缩的项目以 Base64 data URL 的形式直接嵌入到”Open in Ayakaleaf”链接中。这样无需将文件托管在单独的 URL 上，即可创建导入链接。

内容	参数	Data URL 格式
LaTeX 文件	snip_uri	data:application/x-tex;base64,<base64-encoded-tex>
zip 压缩项目	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>

要导入 zip 压缩的项目，请将 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 资源。有关配置和网络访问限制，请参阅出站代理。