Puppeteer 本身不支持直接加载 Tampermonkey 脚本，但可通过将其封装为 Chrome 扩展并在启动时加载该扩展的方式实现等效功能。本文详解完整实现流程、注意事项及可复用的工程化方案。
虽然 puppeteer 本身不支持直接加载 tampermonkey 用户脚本，但可通过将其封装为 chrome 扩展并在启动时加载该扩展的方式实现等效功能。本文详解完整实现流程、注意事项及可复用的工程化方案。
在 Puppeteer 中“运行 Tampermonkey 脚本”，本质上是希望在自动化浏览器环境中复现用户脚本（如 DOM 操作、请求拦截、定时注入等）的行为。由于 Tampermonkey 是一个依赖宿主浏览器环境（含其沙箱、API 和 UI 层）的第三方扩展，而 Puppeteer 启动的是纯净、无扩展的 Chromium 实例，因此无法直接注入或执行 .user.js 文件。官方文档与社区实践均表明：唯一可靠、稳定且符合 Chromium 架构的设计路径，是将目标用户脚本转换为标准 Manifest V3 Chrome 扩展，并通过 --load-extension 参数在 Puppeteer 启动时加载。
✅ 正确实现步骤
-
创建最小化扩展目录结构（例如 tampermonkey-ext/）：
tampermonkey-ext/ ├── manifest.json └── content.js
-
编写 manifest.json（Manifest V3）：
{ "manifest_version": 3, "name": "My Tampermonkey Script", "version": "1.0", "content_scripts": [{ "matches": ["<all_urls>"], "js": ["content.js"], "run_at": "document_idle", "all_frames": true }], "permissions": ["scripting", "activeTab"] }⚠️ 注意：
可按需替换为具体匹配规则（如 "https://example.com/*"），避免过度权限；run_at: "document_idle" 等效于 Tampermonkey 的 @run-at document-idle。 将原 .user.js 逻辑迁移至 content.js
删除所有元数据块（如 // ==UserScript==），仅保留纯 JavaScript 逻辑。若原脚本使用 GM_* API（如 GM.xmlHttpRequest），需改用原生 fetch 或 chrome.runtime.sendMessage 配合 background service worker 实现（Manifest V3 不再支持 webRequest blocking 权限，需权衡替代方案）。-
Puppeteer 启动时加载扩展：
const puppeteer = require('puppeteer'); (async () => { const browser = await puppeteer.launch({ headless: 'new', // 推荐使用 'new' 模式（Chromium 117+） args: [ `--load-extension=${require('path').resolve('./tampermonkey-ext')}` ] }); const page = await browser.newPage(); await page.goto('https://example.com'); // 脚本已在页面加载时自动执行 await browser.close(); })();
⚠️ 关键注意事项
- Headless 模式限制：Chromium 的 headless=new 模式支持加载扩展，但 headless=old（已废弃）完全不支持。务必使用 headless: 'new'。
- 扩展路径必须为绝对路径：--load-extension 不接受相对路径，需用 path.resolve() 显式转换。
- 跨域与权限：若脚本需访问跨域资源，请在 manifest.json 中声明对应 host_permissions（V3 要求显式声明）。
- 调试建议：启动时添加 devtools: true 并打开 chrome://extensions，启用“开发者模式”后可查看扩展 ID 与错误日志。
- 生产部署提示：扩展目录应打包进部署包，避免路径失效；CI/CD 环境中注意文件权限（Linux/macOS 下需确保可读）。
✅ 总结
将 Tampermonkey 用户脚本迁移到 Puppeteer 的本质，不是“模拟 Tampermonkey”，而是以标准 Web Extension 方式复现其行为。这种方式完全兼容 Puppeteer 的生命周期管理、可调试、可版本化，且规避了注入 <script> 标签带来的执行时机不可控、CSP 限制、作用域隔离等问题。对于需要长期维护的自动化任务，这是最健壮、可扩展的工程实践。</script>
