react-pdf设置cmapUrl时出现sendWithPromise读取null属性错误求助

问题原因 #

1. 非英文字体PDF无法渲染：react-pdf默认未内置CJK等非拉丁字符的CMAP（字符映射）文件，缺少这些文件时无法解析对应字符，导致文本不显示，同时触发cmapreaderfactory not initialized警告。
2. 添加CMAP后触发sendWithPromise错误：核心原因是CMAP资源路径配置错误或Worker初始化与CMAP加载的时序冲突——PDF Worker实例未完成初始化就尝试加载CMAP资源，进而抛出worker为null的异常。

解决办法 #

方法1：本地Vite项目正确配置CMAP #

1. 安装CMAP插件：

npm install @react-pdf/cmap-webpack-plugin --save-dev

2. 修改Vite配置文件（vite.config.js）：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import CMapPlugin from '@react-pdf/cmap-webpack-plugin';

export default defineConfig({
  plugins: [
    react(),
    CMapPlugin({
      outputDir: 'public/cmaps', // CMAP资源输出目录
      publicPath: '/cmaps/',     // 页面访问CMAP的基础路径
    }),
  ],
});

3. 在<Document>组件中指定CMAP路径：

import { Document, Page } from '@react-pdf/renderer';

function PDFViewer({ pdfUrl }) {
  return (
    <Document
      file={pdfUrl}
      cmapUrl="/cmaps/"
      cmapPacked={true}
    >
      <Page pageNumber={1} />
    </Document>
  );
}

4. 重启Vite服务，确认public/cmaps目录已生成CMAP资源文件。

方法2：使用CDN加载CMAP（规避本地配置问题） #

如果本地配置仍报错，直接用官方CDN的CMAP资源，同时确保Worker提前初始化：

import { Document, Page, pdfjs } from '@react-pdf/renderer';

// 提前初始化PDF Worker，指定对应版本的Worker脚本地址
pdfjs.GlobalWorkerOptions.workerSrc = `//unpkg.com/pdfjs-dist@${pdfjs.version}/build/pdf.worker.min.js`;

function PDFViewer({ pdfUrl }) {
  return (
    <Document
      file={pdfUrl}
      cmapUrl="//unpkg.com/pdfjs-dist@3.4.120/cmaps/"
      cmapPacked={true}
    >
      <Page pageNumber={1} />
    </Document>
  );
}

注意：pdfjs.version需与你安装的@react-pdf/renderer依赖的pdfjs版本一致，避免版本不兼容。

额外排查点 #

• 检查网络请求：打开浏览器开发者工具，查看.bcmap格式的CMAP资源是否能正常加载（Network面板搜索），若返回404则说明路径配置错误。
• 版本兼容性：确保@react-pdf/renderer为最新稳定版（>=3.1.12），旧版本可能存在Worker与CMAP的兼容问题。
• SSR场景适配：若为Next.js等SSR项目，需确保<Document>组件仅在客户端渲染（比如用useEffect动态挂载，或通过dynamic组件禁用SSR）。

内容的提问来源于stack exchange，提问作者amu03