本文详解 Firefox 扩展（Manifest V2）中无法直接使用 ES 模块导入 html2pdf 的根本原因，并提供兼容性解决方案：通过全局脚本引入 + window.html2pdf 调用，绕过模块限制，实现对 GitHub Pages 等整站内容的 PDF 导出。

本文详解 firefox 扩展（manifest v2）中无法直接使用 es 模块导入 html2pdf 的根本原因，并提供兼容性解决方案：通过全局脚本引入 + `window.html2pdf` 调用，绕过模块限制，实现对 github pages 等整站内容的 pdf 导出。

Firefox 扩展（尤其是 Manifest V2）的内容脚本（content scripts）运行在隔离环境中，不支持原生 ES 模块语法（如 import/export），也不识别 type="module" 属性。因此，当你在 newone.js 中写入 import html2pdf from "dist/html2pdf";，或尝试动态注入模块化脚本时，浏览器会抛出 import declarations may only appear at top level of a module 错误——这不是路径或配置问题，而是平台能力限制。

✅ 正确做法是：将 html2pdf.bundle.min.js（官方预构建的 UMD 版本）作为普通 <script></script> 嵌入扩展资源，并依赖其挂载到 window 对象的全局变量。

✅ 步骤说明

1. 下载并引入 UMD 版本
   前往 html2pdf.js 官方 GitHub Releases 下载 html2pdf.bundle.min.js（非源码 index.js 或 dist/html2pdf.js），放入扩展目录，例如 lib/html2pdf.bundle.min.js。

2. 在 manifest.json 中声明该脚本为 content script 依赖（推荐）
   修改 content_scripts.js 数组，按执行顺序前置引入：

   "content_scripts": [
     {
       "matches": ["*://github.gatech.edu/pages/cs6035-tools/cs6035-tools.github.io/**"],
       "js": [
         "lib/html2pdf.bundle.min.js",
         "newone.js"
       ]
     }
   ]

   ⚠️ 注意：html2pdf.bundle.min.js 必须排在 newone.js 之前，确保 window.html2pdf 在执行业务逻辑前已就绪。

   

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

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

   下载

3. 在 newone.js 中调用全局函数（无需 import）

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

   // ✅ 正确：直接使用 window.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()
   window.html2pdf().from(element).set(opt).save();

? 补充说明与注意事项

• 不要手动修改 html2pdf.js 源码添加 export：UMD 构建已自动处理全局暴露，修改源码易引发兼容性问题且无必要。
• 避免动态插入 <script type="module"></script>：Firefox 不支持 content script 内部执行模块脚本，即使 chrome.runtime.getURL() 返回正确路径也无效。
• Manifest V3 用户注意：V3 支持模块化 content scripts（需 "type": "module" 字段），但需配合 "manifest_version": 3 及更新的权限模型；本方案仍适用于 V2（当前高校项目常用环境）。
• 整站 PDF 的进阶提示：当前示例仅导出 document.body。若需抓取多页（如 GitHub Pages 的所有 .html 文件），需结合 background.js 发起跨域请求 + fetch 渲染 DOM 后再调用 html2pdf，此属延伸功能，不在基础集成范围内。

通过以上方式，你即可绕过模块系统限制，在 Firefox 扩展中稳定调用 html2pdf 实现高质量 PDF 导出——简洁、可靠、符合 WebExtensions 规范。