VSCode配置Node环境需确保终端识别node/npm，Puppeteer生成PDF成败取决于Chromium下载、权限及无头兼容性；须验证PATH、安装匹配版本、设置viewport与waitUntil、显式close浏览器，并排查字体、CSS和渲染上下文问题。
VSCode 本身不提供 Node 运行时，配置 Node 环境的关键是确保终端和调试器都能正确识别 node 和 npm，而 Puppeteer 生成 PDF 的成败往往卡在 Chromium 下载、权限、或无头模式兼容性上——不是装了就能跑。
确认 VSCode 使用的是系统 PATH 中的 Node
很多人以为装了 Node 就万事大吉，但 VSCode 启动方式（比如从桌面图标或 Spotlight 打开）可能导致它无法继承 shell 的 PATH，从而在集成终端里执行 node -v 报 “command not found”。
- 在 VSCode 终端中运行
which node（macOS/Linux）或where node（Windows），看路径是否指向你安装的 Node（如/usr/local/bin/node或C:\Program Files\nodejs\node.exe） - 如果返回空或错误路径，重启 VSCode 前先用 shell 启动：
code .（macOS/Linux）或code .从 PowerShell/Command Prompt（Windows） - 检查 VSCode 设置里的
terminal.integrated.env.linux/.osx/.windows，必要时手动补全 PATH，例如添加"PATH": "/usr/local/bin:${env:PATH}"
初始化项目并安装 Puppeteer（注意版本与 Chromium 兼容性）
Puppeteer v20+ 默认下载 Chromium 120+，某些旧系统（如 CentOS 7、Ubuntu 18.04）缺依赖库，puppeteer.launch() 会静默失败或报 Failed to launch browser。
Zenlink - Node SDK for ZenHeart
下载
ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。
- 用
npm init -y初始化项目，再执行npm install puppeteer@latest（不推荐puppeteer-core，除非你明确自己管理浏览器二进制） - 首次安装时观察终端输出：是否成功解压
chromium？若卡在 “Downloading Chromium” 或报 TLS 错误，可临时设环境变量：PUPPETEER_DOWNLOAD_HOST=https://npmmirror.com/mirrors（国内镜像） - 若不想下载 Chromium（比如部署到已有 Chrome 的服务器），改用
puppeteer.launch({ executablePath: '/usr/bin/chromium-browser' })，但必须确保该 Chrome 版本 ≥ Puppeteer 要求的最低版本（查package.json中peerDependencies）
写一个最小可行 PDF 生成脚本（避开常见挂起陷阱）
直接调 page.pdf() 却没等页面加载完成，或没关闭浏览器，会导致进程不退出、PDF 文件为空或损坏。
- 必须 await
page.goto()，且建议加{ waitUntil: 'networkidle0' }，避免因懒加载资源未完成就截图 -
page.pdf()前最好显式设置视口：await page.setViewport({ width: 1280, height: 800 })，否则默认 800×600 可能截不全内容 - 务必调用
browser.close()，否则 Node 进程常驻，VSCode 调试器也关不掉；可用try...finally保证执行 - 示例片段：
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.setViewport({ width: 1280, height: 800 });
await page.goto('https://example.com', { waitUntil: 'networkidle0' });
await page.pdf({ path: 'output.pdf', format: 'A4' });
await browser.close(); // 关键
})();
调试 PDF 输出异常（空白、截半、字体缺失）
PDF 看起来“不对”，大概率不是 Puppeteer bug，而是页面渲染上下文或 CSS 行为差异导致。
- 空白 PDF：检查
page.goto()是否被拒绝（加catch打印 error），或页面含前端路由（如 React Router），需确保 URL 是服务端可直出的路径 - 截半/错位：禁用打印媒体查询干扰：
await page.emulateMediaType('screen')；或尝试printBackground: true参数 - 中文乱码/字体缺失：Puppeteer 内置 Chromium 缺少中文字体，Linux/macOS 需提前安装（如 Ubuntu 执行
sudo apt-get install fonts-wqy-zenhei），Windows 一般自带 - 想验证是否真渲染成功？加一句
await page.screenshot({ path: 'debug.png' })，比 PDF 更快暴露渲染问题
真正麻烦的从来不是代码几行，而是 Chromium 在不同系统上的静默行为、字体链 fallback 规则、以及 PDF 导出时对 CSS 分页（@page）的支持程度——这些没法靠重装解决，得对着生成的 debug.png 和终端日志一行行比对。
