您现在的位置：程式碼之家 >> 編程語言 > >> 更多程式語言 >> 程式設計疑難解答

前端實現網頁截圖保存為圖片：html2canvas 完整指南

編輯：程式設計疑難解答

核心方案：html2canvas 庫

html2canvas 是純 JS 實現的客戶端截圖庫，遍歷 DOM 計算樣式，在 `

完整可執行代碼

1. 引入庫（CDN 或 npm）

<!-- HTML 引入 -->
<script src="https://cdn.jsdelivr.net/npm/html2canvas@1.4.1/dist/html2canvas.min.js"></script>

<!-- 或 npm -->
npm install html2canvas

2. HTML 結構

<div id="capture-area">
  <h1>這是要截圖的區域</h1>
  <p>包含文字、圖片、CSS 樣式...</p>
  <img src="logo.png" alt="Logo">
</div>
<button id="btn-save">保存為圖片</button>

3. JS 核心邏輯

document.getElementById('btn-save').addEventListener('click', async () => {
  const element = document.getElementById('capture-area');
  const btn = document.getElementById('btn-save');
  btn.disabled = true;
  btn.textContent = '生成中...';

  try {
    // 核心 API
    const canvas = await html2canvas(element, {
      useCORS: true,           // 支援跨域圖片（需圖片伺服器配置 Access-Control-Allow-Origin）
      scale: 2,                // 2倍縮放，提高清晰度
      logging: false,
      backgroundColor: '#fff'  // 背景色，預設透明
    });

    // 轉為圖片下載
    const dataUrl = canvas.toDataURL('image/png', 1.0);
    const link = document.createElement('a');
    link.href = dataUrl;
    link.download = `webpage_${Date.now()}.png`;
    link.click();
  } catch (err) {
    console.error('截圖失敗', err);
    alert('截圖失敗，請查看控制台');
  } finally {
    btn.disabled = false;
    btn.textContent = '保存為圖片';
  }
});

關鍵配置選項詳解

選項	用途	建議值
`scale`	縮放倍數，解決高 DPI 模糊	`window.devicePixelRatio` 或 `2`
`useCORS`	嘗試跨域載入圖片	`true`（需圖片端支援 CORS）
`backgroundColor`	Canvas 背景色	`'#ffffff'` 或 `null`(透明)
`ignoreElements`	過濾不需截圖的元素	`(el) => el.id === 'btn-save'`
`onclone`	克隆文檔後回調，可修改樣式	隱藏滾動條、修正 fixed 定位

常見坑點與解決

跨域圖片空白：圖片伺服器**必須**返回 `Access-Control-Allow-Origin: *` 或指定域名；否則瀏覽器汙染 Canvas，導致 `toDataURL` 拋安全異常。
替代方案：後端代理圖片 / 轉 Base64 內聯。
Fixed/Sticky 定位錯位：html2canvas 克隆文檔時會改變定位上下文。在 `onclone` 回調中將 `position: fixed` 改為 `absolute` 並手動計算座標。
超長頁面截圖空白/崩潰：Canvas 尺寸受限於瀏覽器最大限制（通常 32767px）。分頁截圖拼接或使用 `rasterizehtml` / 後端無頭瀏覽器方案。
中文字體渲染異常：確保字體已載入（`document.fonts.ready`）後再截圖。

進階：Vue/React 組件封裝

<!-- Vue 3 組件範例 -->
<script setup>
import html2canvas from 'html2canvas';
const targetRef = ref(null);
const capture = async () => {
  const canvas = await html2canvas(targetRef.value, { scale: 2 });
  // 下載邏輯...
};
</script>
<template>
  <div ref="targetRef">...內容...</div>
  <button @click="capture">截圖</button>
</template>

html2canvas 適合「用戶主動觸發、當前可視區域、結構相對固定」的輕量截圖需求。複雜報表、PDF 導出、後端定時生成請轉向 Puppeteer/Playwright 等無頭瀏覽器方案。