# 常见问题与故障排查

关于入门、项目、编译、助手和备份的快速解答。

## 入门

### 我需要账号吗？

不需要。下载 Oleafly，打开，就可以写作。云端 AI 提供商、GitHub 或 Dropbox 等可选服务使用它们各自的账号。

### Oleafly 支持 LaTeX、Typst 和 Markdown 吗？

支持。创建项目时选择引擎。每种引擎有各自的编辑和导出能力。[快速入门](/docs/getting-started/)会带你生成第一份 PDF。

### 我可以带入已有的论文或简历吗？

可以。你可以导入项目源码、ZIP 压缩包或 Git 仓库。Oleafly 还提供了 DOCX 和基于文本的 PDF 的转换路径。请阅读[导入已有项目](/docs/import-project/)，选择合适的方式。

### 可以离线工作吗？

没有云端连接时，你也可以写作、整理文件、使用本地校对，以及运行已下载的本地 AI 模型。Tectonic 可以用已缓存的宏包编译。新宏包、远程参考文献、云端模型、GitHub 和下载都需要联网。离线之前，请先成功编译一次，把项目准备好。

### 我的文件在哪里？

你的项目是本地库中的普通文件夹。你可以复制它们、备份它们，或在其他工具中打开它们。[数据存放在哪里](/docs/where-your-data-lives/)介绍了项目文件、应用设置和检查点。

### 我可以用 Oleafly 写学位论文或简历吗？

可以。从[学位论文工作流](/docs/workflows/thesis/)或[简历工作流](/docs/workflows/resume/)开始。它们和研究论文使用同样的编辑器、预览、参考文献和导出工具。

## 安装

### 操作系统阻止了安装程序

请确认文件来自[官方发布页](https://github.com/Oleafly/Oleafly/releases/latest)，并且与你的平台相符。按照[安装指南](/docs/install/#first-launch)中该平台的首次启动步骤操作。

### 我该用哪个 Linux 安装包？

选择与你电脑匹配的架构，然后选 AppImage、Debian 软件包或 RPM。系统要求参见 [Linux 安装](/docs/install/#linux)。

## 编译

### 我的第一次编译很慢

Tectonic 可能需要下载这份文档用到的宏包，一台电脑上的首次编译还会获取一批常用宏包。它们会被缓存，供之后的构建使用。宏包仍在下载时，编译可以超过通常的五分钟时限。打开[日志](/docs/compiling/#reading-the-logs)可以看到正在发生什么。

### 缺少宏包

如果离线模式已开启，请在提示中选择 **关闭并编译**，或者把它关闭一次编译，以获取该宏包。在系统 TeX 工具链上，请使用错误中的 **查找并安装**。来自 Debian、Ubuntu 或 Fedora 的 TeX Live 通过 `apt` 或 `dnf` 获取宏包。参见 [LaTeX 引擎与宏包](/docs/latex-engines/#recover-from-a-missing-file)。

### 我选了 pdfLaTeX，Oleafly 却要求安装 TeX 发行版

pdfLaTeX、XeLaTeX、LuaLaTeX、upLaTeX 和 pLaTeX 运行在你电脑上安装的 TeX 发行版之上。没有安装时，选择其中任何一个都会在编译之前打开一个对话框。选择 **下载并使用 TinyTeX** 来安装一个，或选择 **切换回 Tectonic** 回到内置引擎。编译失败后，预览会以 **下载并使用 TinyTeX** 和 **使用 Tectonic** 的形式提供同样的选择。参见[没有安装 TeX 时](/docs/latex-engines/#when-no-tex-is-installed)。

### MiKTeX 提示 latexmk 需要 Perl

MiKTeX 的 `latexmk` 运行在 Perl 之上，而 MiKTeX 不包含 Perl。请安装 Strawberry Perl，或从 **设置 → 引擎 → LaTeX** 安装 TinyTeX，它自带 Perl，并会从 MiKTeX 手中接管编译。参见 [MiKTeX 与 Perl](/docs/latex-engines/#miktex-and-perl)。

### 我的 PDF 中缺少文字

字体没有这些字符的字形。这种情况最常见于韩文、中文和日文文本，TeX 会略去这些字符，而不让编译失败。Oleafly 会发出警告，并在日志中列出它们。在 LaTeX 中，请粘贴警告里为你的文字给出的设置。在 Typst 中，请下载通知提供的字体包，或把包含这些字符的字体添加到项目的 `fonts` 文件夹。在 Markdown 中，请在 YAML 头部把 `mainfont` 或 `CJKmainfont` 设为包含它们的字体。参见[PDF 中缺失的字符](/docs/latex-engines/#characters-missing-from-the-pdf)和[显示为方框的字符](/docs/typst/#characters-that-show-as-boxes)。

### Oleafly 因为耗时太长停止了我的编译

一次编译最长可以运行 5 分钟。宏包仍在下载时，时限最多会延长到 30 分钟。Markdown 转 PDF 有 15 分钟，Quarto 和 Calepin 有一个小时。请再编译一次：下载会从中断的地方继续。对于 Tectonic 上的长草稿，请在编译菜单中把 **编译模式** 设为 **快速**。

### 新项目可以使用我自己的 TeX 安装吗？

可以。打开 **设置 → 引擎 → LaTeX**，把 **默认编译引擎** 设为 **latexmk（系统 TeX）**。之后新建、导入和转换的 LaTeX 项目都会从它开始。参见[为新项目设置默认值](/docs/engines/#set-a-default-for-new-projects)。

### 我的文档使用了 minted 或 PythonTeX

这些宏包会在文档编译时运行其他程序，而 Oleafly 默认会阻止这一点。它们需要系统 LaTeX。如果你信任项目中的每个文件，请选择编辑器上方横幅中的 **允许外部命令**。参见[允许外部命令](/docs/latex-engines/#allow-external-commands)。

### 编译完成了，但有警告

打开 **日志**，先检查未定义的引用和交叉引用。在导出之前，[预检](/docs/preflight/)可以帮你找到受影响的源码位置。

### 我看不懂某个构建错误

让助手读取日志、修复错误，然后再次编译。如果你想在过程中审阅它提出的操作，请使用 **请求批准**。你也可以把日志贴到 [Discord](/discord) 的求助论坛里。

### 为什么缺少某种导出格式？

可用的格式取决于引擎和文档类型。请查看[导出表格](/docs/export/#editable-formats)。

## AI 助手

### 我可以使用哪种助手？

可以连接模型提供商、使用本地模型，或选择 [CLI 代理](/docs/cli-agents/)。[设置 AI](/docs/ai-setup/) 介绍了每条路径。

### 使用编辑器必须有 AI 吗？

不必。写作、编译、引用、预览、图表、项目历史和导出，不用助手也都能使用。

### 助手能做什么？

它可以处理项目文件、查找文献来源、检查 PDF、创建图片、运行工具，并帮助修复构建。请选择适合这项工作的计划和批准策略。参见[聊天与工具](/docs/ai-chat/)。

### 模型旁边的“已验证”是什么意思？

该模型通过了一次工具调用探测。它帮助你选择适合项目操作的模型；它不评估模型写作或研究的质量。参见[设置 AI](/docs/ai-setup/)。

### 为什么用量显示为“未知”？

有些提供商和 CLI 代理不会报告用量。“未知”表示这个值不可用。请阅读[用量与预算](/docs/ai-usage/)。

### 我可以连接外部助手吗？

可以。使用内置的 [CLI 代理连接](/docs/cli-agents/)，启用 Oleafly 的本地 [MCP 服务器](/docs/mcp/)，或把你的代理连接到 [`oleafly` 命令](/docs/cli/)，它在应用关闭时同样可用。

## 历史与协作

### 怎样恢复较早的版本？

打开[检查点](/docs/checkpoints/)，对比成功构建时的源码并恢复某个版本。你自己管理的 Git 提交则使用[源代码管理](/docs/git-history/)。

### 我可以和合著者一起工作吗？

可以。通过[实时协作](/docs/collaboration/)，你和合著者借助你们团队运行的协作服务器同时编辑同一个项目。你们每个人都在自己的电脑上以文件的形式保存项目。你也可以分享源码归档，或使用 [GitHub 同步](/docs/github-sync/)来交换提交。

### 我可以在两台电脑上使用我的项目吗？

可以。[云同步](/docs/cloud-sync/)会把你的库项目和设置保存在你自己的 Dropbox 中，你连接的每台电脑都可以下载它们。打开 **设置 → 数据存储 → 云同步** 即可连接。你也可以用 [GitHub 同步](/docs/github-sync/)在电脑之间转移项目。

### 导出源码就备份了全部内容吗？

它备份的是项目源码。自动检查点、应用偏好设置和凭据是分开存放的。请按照[备份指南](/docs/where-your-data-lives/#back-up-your-work)把你需要的内容也包含进去。

## 报告问题

打开 **设置 → 帮助与关于 → 复制信息**，把这些信息连同简短的描述、重现问题的步骤和相关日志一起提供。请在 [Issues](https://github.com/Oleafly/Oleafly/issues) 中报告问题；提问和工作流方面的帮助请用 [Discord 社区](/discord)。
