pdf.js预览PDF签名不显示

Question

使用pdf.js预览PDF时，数字签名区域显示为空白或仅显示占位框，无法正常呈现签名外观。该问题通常出现在含有PKCS#7或PAdES标准数字签名的PDF文档中。尽管pdf.js能解析签名字段结构，但由于缺乏对嵌入式签名外观（如图像、墨迹签名）的完整渲染支持，导致视觉上“签名不显示”。此外，浏览器安全策略限制了部分底层加密操作，也影响签名内容的解密与绘制。开发者常误以为是加载异常，实则为功能局限。如何在前端正确还原签名可视化效果，成为集成电子签章系统时的关键难题。

Answer 1

1. 问题背景与现象描述

在现代电子文档系统中，PDF 文件的数字签名已成为保障文件完整性与法律效力的核心手段。尤其在金融、政务、医疗等行业，广泛采用符合 PKCS#7 或 PAdES 标准的数字签名技术。然而，当使用 pdf.js 在前端预览此类已签名 PDF 时，常出现签名区域显示为空白或仅呈现占位框的现象。

开发者往往误以为是 PDF 加载失败或字段解析错误，实则该行为源于 pdf.js 的设计限制：它虽能识别签名字段结构（如 /SigFlags、/V、/Contents 等），但并未实现对嵌入式签名外观（appearance stream）的完整渲染支持，尤其是包含图像、手写体或企业徽标的视觉元素。

• 现象：签名字段存在但无图形内容
• 根源：缺少对 AP（Appearance Dictionary）和签名图像资源的解码与绘制能力
• 附加限制：浏览器同源策略与 SubtleCrypto API 权限控制阻碍了签名内容的解密操作

2. 技术原理剖析：PDF 数字签名结构

PDF 中的数字签名基于 ISO 32000-1 规范，通常由以下几个关键组件构成：

组件	说明	相关对象类型
SigField	表单字段，标记为签名域	/WidgetAnnotation, /Sig
Signature Dictionary	包含签名元数据，如 Filter、SubFilter、M（时间）、Name	/V
PKCS#7 / CMS 数据	实际签名值，编码为 ASN.1 结构	/Contents
Appearance Stream (AP)	可选的可视化表示，决定签名如何“看起来”	/AP > /N
Embedded Image Resources	可能嵌入签名图片（如公司章、手签图）	/XObject > /Image

pdf.js 能成功提取前四项信息，但在处理 AP 字典中的绘图指令（特别是涉及图像 XObject 的引用）时，由于缺乏完整的图形上下文支持，导致最终无法合成视觉输出。

3. 分析过程：从日志到代码追踪

为定位问题，可通过以下步骤进行深度分析：

1. 启用 pdf.js 的调试模式：PDFJS.verbosity = 1;
2. 检查控制台输出是否报告 "Missing appearance for widget annotation"
3. 使用 pdfjsLib.getDocument() 获取文档后，遍历 AcroForm 字段：

async function inspectSignatures(pdfUrl) {
  const loadingTask = pdfjsLib.getDocument(pdfUrl);
  const pdf = await loadingTask.promise;
  
  const formInfo = await pdf.getAnnotations({ type: 1 }); // 获取表单字段
  formInfo.forEach(field => {
    if (field.fieldType === 'Sig') {
      console.log('Found signature field:', field);
      console.log('Has AP?', !!field.appearance);
      console.log('Normal appearance stream:', field.appearance?.normal);
    }
  });
}

若 field.appearance 存在但未被渲染，则说明 pdf.js 解析器未将其注入 canvas 绘制流程。

4. 核心限制：浏览器环境与安全边界

即便修复了外观流渲染逻辑，仍面临浏览器层面的根本性约束：

• CORS 限制：远程 PDF 若未正确配置 CORS 头，将阻止子资源加载（如签名图像）
• 加密操作受限：验证 PKCS#7 签名需调用 Web Crypto API，但部分算法（如 SM2、RSA-PSS）在某些浏览器中不可用或需用户授权
• 沙箱隔离：iframe 嵌入场景下，postMessage 通信延迟可能导致签名状态同步失败

这些因素共同构成了“签名可见性丢失”的复合型成因，非单一代码缺陷所致。

5. 解决方案路径对比

针对上述挑战，业界已有多种应对策略，各具优劣：

方案	实现方式	优点	缺点	适用场景
服务端预渲染	使用 PDFBox/Adobe API 提前生成带签名图层的静态页	兼容性强，完全可控	增加服务器负载，实时性差	高合规要求系统
WebAssembly 扩展	集成 MuPDF 或 Poppler wasm 模块增强渲染能力	接近原生性能，支持复杂图形	包体积大，调试困难	桌面级 Web 应用
自定义 Overlay 渲染	通过页面坐标叠加 HTML/CANVAS 图层模拟签名外观	轻量，灵活定制 UI	需精确坐标映射，响应式适配复杂	中低安全等级场景
PDF 修改注入 AP	使用 Hummus.js 或 qpdf 在签章时强制写入标准化 AP 流	一劳永逸解决客户端问题	改变原始文件哈希，影响签名有效性	内部闭环流程

6. 推荐架构设计：混合式签名可视化方案

结合安全性与用户体验，建议采用如下分层架构：

graph TD A[客户端] --> B{PDF 是否含有效签名?} B -- 是 --> C[调用 Web Crypto 验证签名有效性] C --> D[提取签名位置与尺寸] D --> E[向服务端请求签名图像模板] E --> F[在 Canvas 上叠加渲染签名图层] B -- 否 --> G[按普通字段处理] H[服务端] --> I[存储经审核的签名图像 Base64] I --> E style F fill:#e0f7fa,stroke:#0069c0 style I fill:#fff3e0,stroke:#ff8f00

此模式既避免了直接暴露敏感图像资源，又弥补了 pdf.js 渲染短板，同时保持前端轻量化。

7. 实践示例：Overlay 方式实现签名展示

以下代码片段展示了如何基于字段坐标，在指定页面上叠加签名图像：

function renderSignatureOverlay(pageView, sigField, imageUrl) {
  const { x, y, width, height } = sigField.rect;
  const viewport = pageView.viewport;

  // 计算相对于 canvas 的像素坐标
  const transform = viewport.transform;
  const offsetX = x * transform[0];
  const offsetY = (viewport.height - y - height) * transform[3];

  const img = new Image();
  img.src = imageUrl;
  img.onload = () => {
    const ctx = pageView.canvasContext;
    ctx.drawImage(img, offsetX, offsetY, width * transform[0], height * transform[3]);
  };
}

注意：需确保 sigField 来自已解析的注释数据，并经过合法性校验。

8. 未来展望：标准演进与社区动向

pdf.js 社区已在 GitHub #12798 中讨论增强签名渲染功能，计划引入更完整的 AP 处理模块。Mozilla 团队也在探索与 WebAssembly 加密库（如 asmcrypto.js）集成的可能性，以支持离线签名验证。

随着 W3C WebAppSec 工作组推动 Trusted Types 和 Policy-based Isolation 机制落地，未来有望在不牺牲安全的前提下，开放更多底层操作权限，从而彻底解决此类“功能可见性缺口”问题。