React-PDF 中多页渲染时文本层缩放异常问题分析

问题现象

在使用 React-PDF 库渲染多页 PDF 文档时，开发者发现了一个奇怪的现象：当使用 <Document> 组件同时渲染多个 <Page> 时，从第二页开始的部分页面会出现文本层（Text Layer）缩放异常的问题。具体表现为某些文本元素的 scaleX 变换值被错误地放大，导致文本层与底层 PDF 内容不匹配。

问题复现条件

这个问题具有以下特征：

1. 仅影响部分 PDF 文档，并非所有文档都会出现
2. 第一页始终正常，问题从第二页开始出现
3. 在单页模式下（仅渲染当前页）不会出现此问题
4. 问题与 PDF.js 版本无关，测试了 9.0 和 9.1 版本都存在
5. 使用 PDF.js 官方演示查看相同文档时不会出现此问题

技术分析

经过深入分析，发现问题根源在于 PDF.js 内部用于计算文本宽度的 Canvas 测量机制存在竞态条件。PDF.js 为了提高性能，使用了一个静态 Canvas 上下文来测量文本宽度：

1. 文本测量过程依赖 canvas.measureText 方法
2. 测量前需要正确设置 Canvas 的字体属性（大小、字族）
3. 在多页并行渲染时，不同页面的文本测量会相互干扰
4. 当字体属性设置不当时，测量出的文本宽度会出错
5. 错误的宽度值会导致计算出的 scaleX 变换值异常

解决方案

目前有三种可行的解决方案：

1. 互斥锁方案（推荐）

通过引入互斥锁（Mutex）确保同一时间只有一个页面在进行文本层渲染：

// 使用 async-mutex 库实现
const pageLoadLock = new Mutex();

function PageWrapper({ pageNumber }) {
  const [readyToLoadTextLayer, setReadyToLoadTextLayer] = useState(false);
  
  useEffect(() => {
    const acquireLock = async () => {
      const releaseLock = await pageLoadLock.acquire();
      setReadyToLoadTextLayer(true);
      return releaseLock;
    };
    
    const releasePromise = acquireLock();
    return () => {
      releasePromise.then(release => release());
    };
  }, [pageNumber]);

  return (
    <Page
      pageNumber={pageNumber}
      renderTextLayer={readyToLoadTextLayer}
      onRenderTextLayerSuccess={() => pageLoadLock.release()}
    />
  );
}

2. 条件渲染方案

仅渲染当前可见页面的文本层，其他页面不渲染文本层：

function PageWrapper({ pageNumber, currentPage }) {
  return (
    <Page
      pageNumber={pageNumber}
      renderTextLayer={pageNumber === currentPage}
    />
  );
}

3. 强制清除变换方案

作为临时解决方案，可以在文本层渲染完成后手动清除所有变换：

const removeTextLayerOffset = () => {
  document.querySelectorAll("span[role='presentation']").forEach(span => {
    (span as HTMLElement).style.transform = '';
  });
};

// 使用方式
<Page onRenderTextLayerSuccess={removeTextLayerOffset} />

最佳实践建议

1. 对于需要完整文本层功能的应用，推荐使用互斥锁方案
2. 对于阅读器类应用，条件渲染方案更为合适
3. 临时解决方案会丢失 PDF.js 的精细文本对齐调整，可能导致微小偏差
4. 在生产环境中，建议监控和记录出现问题的特定 PDF 特征

总结

React-PDF 的多页渲染文本层问题源于 PDF.js 的文本测量竞态条件。通过理解底层机制，开发者可以选择最适合自己应用场景的解决方案。对于要求精确文本定位的高要求场景，互斥锁方案提供了最可靠的解决方式，而条件渲染方案则在性能和资源占用上更有优势。