Doc2X 文档

简体中文

English

简体中文

English

主题

Typst 图片路径与项目根目录（--root）

Typst 报 file not found 时，先看它实际查找的路径，再检查文件与目录。项目根目录限定了这份文档能访问的文件范围，--root 用于选择该目录。改变 --root 不会自动改写相对图片路径；源码换了目录，原来的 images/... 可能指向另一个位置。 本教程用同一份真实导出项目的六组本地对照说明差别。

已有 ZIP 可以从完整解压开始；需要从 PDF 生成项目时，打开文档解析，核对结果后按导出格式说明选择 Typst。

先区分原生下载与本地对照

2026-10-12，我们从已解析的两页自编英文 PDF 实际导出了一份 Typst ZIP，包含一个 .typ 和一张 JPEG。2026-10-13，继续用这份未改写的原生下载，在本地建立路径对照：保留完整项目、移动源码、只改图片引用、指定工程根目录。没有新增上传、OCR 或产品导出。

此前真实 Typst 导出配置：保留公式、按原页保留表格，关闭导出前图片高清化。

这是原生 ZIP 对应的实际导出配置截图；截图在成功下载后重新打开弹窗取得，随后取消，没有再导出一次。

文件用途与来源
两页原 PDF自编原稿，用于核对公式、表格、图注与分页
原生 Typst ZIP实际产品下载，源码和图片都未改写
本地编译 PDF本地 Typst 0.15.1 的两页成品，不是产品直接导出的 PDF
六组路径对照包本地制作，含原生 ZIP、源码副本、相同图片、命令、诊断与本地成品

对照包中的 relative.typ 和 root-relative.typ 只修改了一处图片路径；unchanged.typ 的字节与原生源码相同。编译器和字体没有随包分发。

第 1 步：完整解压，先编译原生项目

原生 ZIP 的结构是：

text
pdf-typst-output.typ
images/
  1_279_471_1061_604_0.jpg

在解压目录执行：

bash
typst compile pdf-typst-output.typ output.pdf

本例原生源码第 54 行引用 images/1_279_471_1061_604_0.jpg，相对于这份 .typ 所在目录查找。完整项目即使从另一个工作目录指定主文件路径编译，也能成功；终端当前目录与图片引用的基准不是一回事。

编译器需要预先可用，可查看 Typst 官方获取说明。本轮实测为 Typst 0.15.1，源码指定的 Noto Serif CJK SC 和 STIX Two Text 字体都可用。缺字体时先看诊断和实际 PDF；字体警告、缺字与资源缺失是不同检查，详见编译与字体核对指南。

第 2 步：移动源码后，重新核对引用

对照包把源码放进 nested/src/，图片仍在 nested/images/：

text
nested/
  src/
    unchanged.typ
    relative.typ
    root-relative.typ
  images/
    1_279_471_1061_604_0.jpg

unchanged.typ 仍写着 images/...，因此查找的是 nested/src/images/...。即使已经指定 --root nested，这份源码仍报：

text
error: file not found (searched at nested/src/images/1_279_471_1061_604_0.jpg)

先确认图片确实在项目内，再选择一种与目录一致的引用方式。不要反复重新 OCR，也不要把同一图片随意复制到多个猜测的目录。

第 3 步：设置项目根目录，匹配图片路径

方案 A：从 src/ 返回上一级。 本地副本 relative.typ 将引用改为：

typst
#box(image("../images/1_279_471_1061_604_0.jpg", width: 90.0%))

Typst 默认以主文件所在目录作为项目根。这里若不指定根目录，主文件在 nested/src/，../images/ 会超出该根目录，因此报 would escape the project root。在对照包顶层执行以下命令，把包含源码与图片的 nested 工程目录作为根：

bash
mkdir outputs
typst compile --root nested nested/src/relative.typ outputs/relative.pdf

方案 B：从工程根引用。 root-relative.typ 将图片路径写为 /images/...，并使用同一个根目录：

typst
#box(image("/images/1_279_471_1061_604_0.jpg", width: 90.0%))
bash
typst compile --root nested nested/src/root-relative.typ outputs/root-relative.pdf

Typst 中以 / 开头的资源路径相对于工程根，不是电脑文件系统根目录。只设置这份工程所需的根目录，主文件和图片都应在其中；不需要把根设成整个磁盘。包导入还有独立根目录规则，本例没有包依赖，参见官方路径说明。

六组实际结果与最终验收

项目与图片引用根目录选择本地结果
完整原生项目，images/...；从其他工作目录调用默认主文件目录成功，退出码 0
源码移到 src/，仍为 images/...--root nestedfile not found，退出码 1，无新 PDF
src/relative.typ，../images/...默认 src/would escape the project root，退出码 1
同一 relative.typ--root nested成功，退出码 0
src/root-relative.typ，/images/...默认 src/file not found，退出码 1
同一 root-relative.typ--root nested成功，退出码 0

三组成功条件生成的 PDF 与此前公开成品逐字节一致；比较时编译器、字体和创建时间固定。这个结果说明路径改动正确地找到了同一张图片，不说明原稿内容被补全。

同一原生项目的本地 Typst PDF 第1页，公式和表格可见，第4节标题移到第1页，图表仍在第2页。

此前本地成品的第 1 页预览；本次三组成功输出与它对应的完整 PDF 一致。原稿和成品都是两页，但第 4 节标题与图分在不同页；图顶部此前缺失的说明也没有因编译成功而恢复。继续对照原稿检查公式、单元格、图注和整页布局。

常见问题

为什么加了 --root 还是找不到图片？

--root 决定可访问的项目范围以及 /... 的基准，不会把源码中的 images/... 改成另一个相对位置。先看诊断中的 searched at，再对应目录结构检查。

出现 project root 错误，是原生 ZIP 漏图了吗？

本例不是。原生 ZIP 包含所需图片；报错来自本地重排目录后的副本。先完整解压并保留原生项目，对照副本中的路径修改定位原因。

这里验证了 Typst 网页版、包导入或所有系统吗？

没有。本轮是 macOS arm64 上的本地编译，只有这个英文项目，没有 import、include 或第三方包。云端编辑器、Windows 路径、包依赖、其他字体和编译器版本需要在对应环境另行验证。