将docx转换为typst时，并提取其中的图片
当使用 pandoc 将 docx 转换为 typst 时，图片提取是一个常见需求。Pandoc 本身支持在转换过程中自动提取嵌入在 docx 中的图片，核心是通过指定图片输出目录和资源路径参数来实现。下面我会详细讲解具体方法和完整流程。
一、核心命令与参数说明
首先给出完整的转换命令，再逐一解释关键参数：
# 完整转换命令（将 docx 转为 typst 并提取图片）
pandoc input.docx -o output.typ \
--extract-media=./typst-images \ # 提取图片到指定目录
--resource-path=./typst-images # 指定 typst 查找图片的路径
关键参数解释：
--extract-media=目录路径：
这是提取图片的核心参数，pandoc 会自动将 docx 中嵌入的所有图片（jpg/png/gif 等）提取到该目录下，图片会以哈希值命名（避免重复），同时在生成的 typst 文件中自动引用这些图片。--resource-path=目录路径：
指定 typst 文件查找图片资源的路径，确保 typst 能正确找到提取后的图片（如果不指定，typst 可能无法定位图片）。-o output.typ：指定输出的 typst 文件名。
二、实操步骤（以 Windows/macOS/Linux 通用为例）
- 准备工作：确保已安装 pandoc（可通过
pandoc --version验证）。 - 创建目录（可选但推荐）：
在 docx 文件所在目录下创建图片存放目录，比如typst-images：mkdir typst-images # Linux/macOS # Windows 命令行：md typst-images - 执行转换命令：
进入 docx 文件所在目录，运行上述完整命令（替换input.docx为你的源文件，output.typ为目标文件）。 - 验证结果：
- 查看
typst-images目录，会看到提取出的图片文件； - 打开生成的
output.typ文件，图片引用部分会自动生成类似：
的代码，确保路径正确。#image("typst-images/xxxxxx.png", width: auto)
- 查看
三、进阶优化（解决常见问题）
1. 自定义图片命名（可选）
默认提取的图片是哈希命名，若想更易识别，可转换后手动重命名，同时修改 typst 文件中的图片路径：
# 原自动生成的引用
#image("typst-images/9f86d081884c7d659a2feaa0c55ad015.png", width: auto)
# 修改后（需先将图片重命名为 figure1.png）
#image("typst-images/figure1.png", width: auto)
2. 处理图片路径错误
如果 typst 渲染时找不到图片，检查：
--extract-media指定的目录是否正确；--resource-path是否包含图片目录；- typst 文件中图片路径是否为相对路径（避免绝对路径）。
四、完整示例
假设你的文件结构：
./
└── my-document.docx # 待转换的 docx 文件
执行以下命令：
# 1. 创建图片目录
mkdir typst-images
# 2. 转换并提取图片
pandoc my-document.docx -o my-document.typ --extract-media=./typst-images --resource-path=./typst-images
执行后文件结构：
./
├── my-document.docx
├── my-document.typ # 生成的 typst 文件
└── typst-images/ # 提取出的图片
├── 123456.png
└── 7890ab.jpg
总结
- 核心参数：
--extract-media用于提取图片到指定目录，--resource-path用于指定 typst 查找图片的路径； - 执行流程：创建图片目录 → 执行 pandoc 转换命令 → 验证图片提取和 typst 引用；
- 常见问题：路径错误时检查
--extract-media和--resource-path参数，确保路径为相对路径且目录存在。
通过以上方法，就能在 pandoc 转换 docx 到 typst 的同时，自动提取所有嵌入的图片并保证 typst 能正确引用。
浙公网安备 33010602011771号