本文详解 Firefox 扩展（Manifest V2）中无法直接使用 ES 模块导入 html2pdf 的根本原因，并提供兼容性方案：通过全局脚本引入 + window.html2pdf 调用，规避“import declarations may only appear at top level”报错，实现对 GitHub Pages 等整站内容的 PDF 批量导出。

本文详解 firefox 扩展（manifest v2）中无法直接使用 es 模块导入 html2pdf 的根本原因，并提供兼容性方案：通过全局脚本引入 + `window.html2pdf` 调用，规避“import declarations may only appear at top level”报错，实现对 github pages 等整站内容的 pdf 批量导出。

Firefox 浏览器（截至最新稳定版）的扩展系统对 ECMAScript 模块（ESM）支持有限——content_scripts 不支持 type="module" 或顶层 import 语句。当你在 newone.js 中写 import html2pdf from "dist/html2pdf";，浏览器会立即抛出 SyntaxError: import declarations may only appear at top level of a module，因为该脚本被作为普通 <script></script>（非模块）执行，而 html2pdf 的源码（如 html2pdf.min.js 或 dist/html2pdf.js）内部仍包含 ESM 语法（如 import/export），导致解析失败。

✅ 正确做法是：将 html2pdf 作为传统 UMD/Global 脚本注入页面上下文，而非尝试模块化导入。具体分三步：

1. 下载并托管 html2pdf 全局版本
   前往 html2pdf.js 官方 GitHub Releases 下载 html2pdf.min.js（推荐 v0.9.3+），将其放入扩展根目录（如 lib/html2pdf.min.js）。注意：必须使用 UMD 构建版（含 window.html2pdf 全局挂载），而非 ESM 版本（如 dist/html2pdf.esm.js）。

2. 在 manifest.json 中声明脚本依赖（仅限 Manifest V2）
   将 html2pdf.min.js 添加到 content_scripts.js 数组首位，确保它在 newone.js 之前加载：

   "content_scripts": [
     {
       "matches": ["*://github.gatech.edu/pages/cs6035-tools/cs6035-tools.github.io/**"],
       "js": [
         "lib/html2pdf.min.js",  // ← 必须放在最前！
         "newone.js"
       ]
     }
   ]

   ⚠️ 注意：matches 推荐使用通配符 /** 确保子路径匹配；html2pdf.min.js 必须先加载，否则 window.html2pdf 未定义。

   

   使用华数设计生成高保真HTML原型、演示文稿、动画和设计评审

   使用经过文档化的设计技能，从真实的品牌或项目背景中生成HTML原生原型、幻灯片、动态演示、可视化图表和评审流程。

   下载

3. 在 newone.js 中通过 window.html2pdf 调用 API
   移除所有 import 语句，直接使用全局函数：

   // ✅ 正确：调用全局暴露的 html2pdf 函数
   document.body.style.border = "5px solid red";
   
   const element = document.body;
   const opt = {
     margin: 1,
     filename: 'GTFile.pdf',
     image: { type: 'jpeg', quality: 0.98 },
     html2canvas: { scale: 2 },
     jsPDF: { unit: 'in', format: 'letter', orientation: 'portrait' }
   };
   
   // 注意：调用方式为 window.html2pdf()，而非 html2pdf()
   const worker = window.html2pdf().from(element).set(opt).save();
   console.log("PDF generation triggered.");

? 补充说明与注意事项：

立即学习“前端免费学习笔记（深入）”；

• Manifest V3 用户注意：V3 的 content_scripts 同样不支持原生 ESM，但可通过 importScripts() 在 service worker 中加载（本例为 V2，不适用）；
• 跨域限制：若需抓取 GitHub Pages 外部资源（如 CSS、字体），需在 manifest.json 中添加 "permissions": ["activeTab"] 和对应 host_permissions；
• 性能提示：整站 PDF 生成可能触发内存警告，建议对 element 进行范围限定（如 document.querySelector('.main-content')）；
• 调试技巧：在控制台输入 typeof window.html2pdf 应返回 "function"，若为 undefined，说明脚本未正确加载或路径错误。

通过以上配置，你即可绕过模块系统限制，在 Firefox 扩展中稳定调用 html2pdf 实现学术文档自动化归档——无需构建工具，零依赖改造，符合大学课程项目轻量级交付需求。