Marp CLI 项目中解决 PDF 生成时的图片缓存问题

在 Marp CLI 项目中，用户经常遇到一个棘手的问题：当更新幻灯片中的图片后，Markdown 预览能正确显示新图片，但生成的 PDF 文档却仍然显示旧图片。这种现象通常是由于浏览器缓存机制导致的。

问题根源分析

Marp CLI 在将文档转换为 PDF 时，内部会启动一个浏览器进程。这个浏览器进程在监视和服务器模式下会保持活跃状态，以准备处理 Markdown 文件的更新。图片是否刷新取决于内部浏览器进程和远程图片服务器的缓存规则。

Marp CLI 目前无法修改用于生成 PDF 的内部浏览器的缓存规则。设计上也不打算支持此功能，因为禁用缓存可能会导致性能下降和远程服务器过载。

解决方案

1. 手动添加查询参数

最常用的解决方案是在图片 URL 后添加不影响图片内容的查询参数。这会使浏览器认为这是一个新的 URL，从而绕过缓存获取最新图片。

![](https://example.com/image.jpg)

# 添加无意义的查询参数来更新，如 `?__update=v1`
![](https://example.com/image.jpg?__update=v1)

# 使用不同的查询参数再次更新
![](https://example.com/image.jpg?__update=v2)

2. 使用插件自动化处理

对于需要频繁更新的项目，可以编写一个 Marp 插件来自动为图片 URL 添加唯一参数。以下是示例插件代码：

// engine.config.js
const crypto = require('crypto')

const imageUniqParameterPlugin = (markdownIt) => {
  const imageRuleIndex = markdownIt.inline.ruler.__find__('image')
  if (imageRuleIndex === -1) throw new Error('Parser rule not found: image')

  const originalImageRule = {
    ...markdownIt.inline.ruler.__rules__[imageRuleIndex],
  }

  // 替换现有的 markdown-it 图片规则以添加唯一参数
  markdownIt.inline.ruler.at(
    'image',
    (state) => {
      const originalNormalizeLink = state.md.normalizeLink

      try {
        // 重写 normalizeLink 方法，在解析图片时添加唯一参数
        state.md.normalizeLink = (url) => {
          try {
            const urlObj = new URL(url, 'dummy://dummy.dummy/')

            // 添加唯一参数避免缓存
            urlObj.searchParams.set('__marp_v__', crypto.randomUUID())
            let normalizedUrl = urlObj.toString()

            if (normalizedUrl.startsWith('dummy://dummy.dummy/')) {
              // 移除虚拟协议和主机
              normalizedUrl = normalizedUrl.slice(20)
            }

            return originalNormalizeLink(normalizedUrl)
          } catch (e) {
            console.warn(e)

            // 如果 URL 解析失败，回退到原始 normalizeLink
            return originalNormalizeLink(url)
          }
        }

        return originalImageRule.fn(state)
      } finally {
        // 恢复原始 normalizeLink
        state.md.normalizeLink = originalNormalizeLink
      }
    },
    { alt: originalImageRule.alt }
  )
}

module.exports = {
  engine: ({ marp }) => marp.use(imageUniqParameterPlugin),
}

注意事项

1. 性能考虑：禁用缓存或频繁更改图片 URL 会增加服务器负载，可能导致性能下降。

2. 缓存策略：最佳实践是结合使用合理的缓存策略和版本控制，而不是完全禁用缓存。

3. 本地开发：对于本地开发环境，可以考虑使用开发服务器配置更宽松的缓存规则。

4. 生产环境：在生产环境中，建议采用内容哈希或版本号作为图片文件名或查询参数的一部分，实现更可控的缓存策略。

通过理解这些原理和解决方案，开发者可以更好地控制 Marp CLI 项目中的图片缓存行为，确保 PDF 生成结果与预期一致。