一、html2canvas基础原理与常见问题

html2canvas是一个基于JavaScript的库，它通过解析DOM元素并重新绘制到canvas上，最终生成图片。其核心原理是：遍历目标DOM的所有节点，获取每个节点的样式、文本、图片等信息，然后在canvas上重新绘制这些元素。这种实现方式虽然灵活，但也带来了两个典型问题：

1.1 图片模糊问题

图片模糊的主要原因是html2canvas默认生成的canvas尺寸与实际显示尺寸不匹配。当canvas的物理像素（devicePixelRatio）与逻辑像素不一致时，浏览器会对canvas内容进行缩放，导致图像模糊。例如，在Retina屏幕上，1个CSS像素可能对应2个物理像素，如果canvas尺寸未考虑这一点，生成的图片就会模糊。

1.2 图片偏移问题

图片偏移通常由以下因素导致：

• 滚动位置影响：html2canvas默认从(0,0)位置开始截图，如果目标div不在视口顶部，截图会包含视口上方的空白区域。
• 边距与定位问题：CSS中的margin、padding、position等属性可能被html2canvas错误解析，导致元素位置偏移。
• 异步加载内容：如果截图时某些资源（如图片、字体）尚未加载完成，可能导致布局偏移。

二、解决图片模糊的核心方案

2.1 调整canvas尺寸与缩放比例

function captureDiv(divId, fileName) {
  const element = document.getElementById(divId);
  const scale = window.devicePixelRatio || 1; // 获取设备像素比
  // 创建隐藏的canvas元素
  const canvas = document.createElement('canvas');
  const ctx = canvas.getContext('2d');
  // 获取div的实际尺寸（包含滚动）
  const rect = element.getBoundingClientRect();
  // 设置canvas尺寸为实际物理像素
  canvas.width = rect.width * scale;
  canvas.height = rect.height * scale;
  // 缩放画布以匹配CSS尺寸
  ctx.scale(scale, scale);
  // 使用html2canvas配置
  html2canvas(element, {
    canvas: canvas,
    scale: scale, // 确保html2canvas使用相同的缩放比例
    logging: true, // 开启日志便于调试
    useCORS: true, // 允许跨域图片
    allowTaint: true // 允许污染画布（谨慎使用）
  }).then(canvas => {
    // 转换为图片并下载
    const link = document.createElement('a');
    link.download = fileName || 'screenshot.png';
    link.href = canvas.toDataURL('image/png');
    link.click();
  });
}

关键点说明：

• devicePixelRatio：获取设备像素比，确保canvas物理像素与显示像素一致。
• canvas.width/height：设置为实际物理像素尺寸（逻辑像素×缩放比例）。
• ctx.scale()：缩放画布上下文，使绘制内容匹配CSS尺寸。

2.2 优化图片质量参数

html2canvas提供了imageQuality参数（0-1），默认值为0.92。对于高清截图，可以设置为1：

html2canvas(element, {
  imageQuality: 1, // 最高质量
  // 其他配置...
});

三、解决图片偏移的实用技巧

3.1 处理滚动位置

function captureWithScroll(divId, fileName) {
  const element = document.getElementById(divId);
  const scrollX = window.scrollX || window.pageXOffset;
  const scrollY = window.scrollY || window.pageYOffset;
  html2canvas(element, {
    scrollX: -scrollX, // 抵消窗口滚动
    scrollY: -scrollY,
    windowWidth: document.documentElement.scrollWidth, // 完整页面宽度
    windowHeight: document.documentElement.scrollHeight, // 完整页面高度
    // 其他配置...
  }).then(canvas => {
    // 下载逻辑...
  });
}

注意事项：

• 如果目标div在滚动容器内（非window），需计算容器相对滚动位置。
• 对于复杂布局，建议将目标div设为position: relative并控制其父级滚动。

3.2 修正CSS样式问题

• 避免使用百分比边距：改用固定像素值。
• 检查定位属性：确保position: absolute/fixed的元素有正确的top/left值。
• 隐藏滚动条：截图前临时隐藏滚动条：

function hideScrollbars() {
  const style = document.createElement('style');
  style.innerHTML = `
    body {
      overflow: hidden !important;
      margin: 0;
      padding: 0;
    }
  `;
  document.head.appendChild(style);
  return style; // 返回以便后续恢复
}

3.3 异步资源加载处理

对于动态加载的内容（如图片、字体），需确保资源加载完成后再截图：

function waitForImages(element, callback) {
  const images = element.querySelectorAll('img');
  let loaded = 0;
  if (images.length === 0) {
    callback();
    return;
  }
  images.forEach(img => {
    if (img.complete) {
      loaded++;
      if (loaded === images.length) callback();
    } else {
      img.onload = () => {
        loaded++;
        if (loaded === images.length) callback();
      };
      img.onerror = () => {
        loaded++;
        if (loaded === images.length) callback();
      };
    }
  });
}
// 使用示例
waitForImages(document.getElementById('target-div'), () => {
  captureDiv('target-div', 'screenshot.png');
});

四、完整优化方案示例

async function optimizedCapture(divId, fileName = 'screenshot.png') {
  // 1. 隐藏滚动条
  const scrollbarStyle = hideScrollbars();
  // 2. 等待所有图片加载
  const element = document.getElementById(divId);
  await new Promise(resolve => {
    waitForImages(element, resolve);
  });
  // 3. 获取设备像素比
  const scale = window.devicePixelRatio || 1;
  // 4. 配置html2canvas
  const options = {
    scale: scale,
    canvas: document.createElement('canvas'),
    logging: true,
    useCORS: true,
    allowTaint: true,
    imageQuality: 1,
    scrollX: -(window.scrollX || window.pageXOffset),
    scrollY: -(window.scrollY || window.pageYOffset),
    windowWidth: document.documentElement.scrollWidth,
    windowHeight: document.documentElement.scrollHeight
  };
  // 5. 执行截图
  try {
    const canvas = await html2canvas(element, options);
    // 6. 下载图片
    const link = document.createElement('a');
    link.download = fileName;
    link.href = canvas.toDataURL('image/png');
    link.click();
  } catch (error) {
    console.error('截图失败:', error);
  } finally {
    // 7. 恢复滚动条
    document.head.removeChild(scrollbarStyle);
  }
}

五、常见问题排查

5.1 截图空白或不全

• 原因：目标div有overflow: hidden或父容器限制尺寸。
• 解决：临时移除限制样式，或调整html2canvas的windowWidth/windowHeight。

5.2 跨域图片无法加载

• 原因：图片服务器未设置CORS头。
• 解决：
  • 使用useCORS: true并确保图片服务器允许跨域。
  • 替代方案：将图片转为base64嵌入HTML。

5.3 字体显示异常

• 原因：自定义字体未加载完成。
• 解决：在@font-face中添加font-display: swap，或等待字体加载后再截图。

六、性能优化建议

1. 限制截图区域：尽量缩小目标div范围，减少canvas处理量。
2. 节流高频调用：避免短时间内多次调用截图。
3. Web Worker处理：将截图逻辑移至Web Worker（需注意DOM访问限制）。
4. 服务端替代方案：对于复杂场景，可考虑使用Puppeteer等无头浏览器方案。

七、总结与最佳实践

1. 始终考虑设备像素比：通过devicePixelRatio和scale参数确保高清输出。
2. 控制滚动与定位：正确处理滚动位置和CSS定位属性。
3. 资源加载同步：确保所有异步资源（图片、字体）加载完成后再截图。
4. 错误处理与恢复：添加try-catch和样式恢复逻辑，避免影响用户体验。
5. 渐进式优化：从基础配置开始，逐步添加高级优化（如跨域处理、字体加载）。

通过以上方法，开发者可以稳定实现html2canvas的高清无偏移截图功能，满足各类业务场景需求。