如何在Asciidoctor中配置图片路径适配整书与单章节生成？

云上老周

2026-8-10

解决Asciidoctor单章节与整书编译的图片路径兼容问题

你的目录结构如下：

book.adoc
chapters/chapter1.adoc
chapters/chapter2.adoc
chapters/chapter3.adoc
images/img1.jpg
images/img2.jpg

目前的问题是：章节里用相对book.adoc的路径引用图片时，整书PDF生成正常，但单独编译章节或预览HTML时，因为章节在chapters/目录下，程序会去chapters/images/找图片，导致加载失败。

不需要移动章节目录，有几个灵活的解决方案：

方案1：用文档属性指定图片路径

在每个章节文件开头加一行配置，指定相对于章节文件的图片目录：
```
:imagesdir: ../images
```
单独编译章节时，这个配置会让程序从chapters/向上一级找images/；整书编译时，Asciidoctor合并文档后会自动处理路径，不会有问题。
也可以不用在文件里写死，编译时通过命令行传参数：
单独编译章节：
```
asciidoctor -a imagesdir=../images chapters/chapter1.adoc
```
整书编译：
```
asciidoctor-pdf -a imagesdir=images book.adoc
```

在book.adoc里定义根目录属性，然后所有章节都用这个属性引用图片：
在book.adoc开头加：
```
:rootdir: .
:imagesdir: {rootdir}/images
```
章节里引用图片时写：image::{imagesdir}/img1.jpg[]
单独编译章节时，通过命令行传递根目录参数：
```
asciidoctor -a rootdir=../ -a imagesdir={rootdir}/images chapters/chapter1.adoc
```
这种方式能统一管理所有资源路径，适合大型项目。