如何在 Puppeteer 中正确保存 PDF 到绝对路径
Puppeteer 的 page.pdf() 方法不支持 file:// 协议前缀的路径，且直接传入绝对路径（如 /Users/.../file.pdf）可能因权限、工作目录或 Node.js 文件系统限制而失败；应使用标准 POSIX 绝对路径字符串（无协议），并确保目标目录存在且进程有写权限。
在 Puppeteer 中生成 PDF 并保存到绝对路径，这事儿看似简单，却是个实实在在的“坑王”。不少人下意识地把路径处理当成一个简单的字符串拼接，结果换来各种 `ENOENT` 错误。其实，核心误区就一个：`page.pdf({ path: ... })` 里的 `path` 选项，它接受的是本地文件系统路径，而不是一个 URL。这意味着，浏览器地址栏里那套 `file://` 协议，在这儿完全行不通。
✅ 正确做法：使用纯净的绝对路径（推荐）
想要稳稳当当，最省心的办法就是使用完整、标准化的绝对路径。这事儿说起来就三步：拼好路径、确保目录存在、然后传进去。别小看第二步，它可是成败关键。
import * as path from path;
import * as fs from fs;
private async convertHtmlToPdf(config: Config, name: string) {
// ✅ 确保目标目录存在（关键！）
const outputDir = /Users/me/TestDirectory;
if (!fs.existsSync(outputDir)) {
fs.mkdirSync(outputDir, { recursive: true });
}
const filename = `${name}-${Math.round(Math.random() * 50)}.pdf`;
const pdfPath = path.join(outputDir, filename); // → /Users/me/TestDirectory/report-42.pdf
const browser = await puppeteer.launch({ headless: new });
const page = await browser.newPage();
await page.setContent(fs.readFileSync(HTML_PATH, utf-8), {
waitUntil: domcontentloaded,
});
await page.emulateMediaType(screen);
// ✅ 直接传入绝对路径字符串（无 file://，无 ~）
await page.pdf({
format: A4,
path: pdfPath, // ← 正确：/Users/me/TestDirectory/report-42.pdf
printBackground: true,
});
await browser.close();
console.log(`✅ PDF sa ved to: ${pdfPath}`);
}
⚠️ 常见错误与修复说明
为了让大家避坑，这里把几个“经典”的错误写法和背后的原因列出来。很多时候，问题不在代码逻辑，而在对路径语义的理解上。
| 错误写法 | 问题原因 |
|---|---|
| path: file://Users/me/... | file:// 是浏览器协议，Node.js 文件系统不识别，导致 ENOENT |
| path: ~/TestDirectory/... | ~ 不会被 Node.js 自动展开，需用 os.homedir() 替代 |
| path: /Users/me/...（但目录不存在） | page.pdf() 不自动创建父目录，需提前 mkdir -p |
| path: ../out/file.pdf（相对路径） | 依赖当前工作目录（process.cwd()），不可靠，尤其在打包或 CI 环境中 |
? 提示：如果对相对路径的最终指向心存疑虑，一个很实用的调试技巧是：通过 `console.log(‘CWD:’, process.cwd())` 打印出当前工作目录，歧义就一目了然了。
? 备选方案：符号链接（适合跨项目/权限受限场景）
当然，有时候直接操作某个绝对路径可能权限不够，或者在跨项目协作时路径太长不好管理。这时，符号链接（Symlink）就是个优雅的解决方案。它的思路是，在项目内部创建一个“快捷方式”，直接指向外部的目标目录。
先在终端执行命令建立链接（需要你有目标目录的写权限）：
# 在终端执行（需有目标目录写权限） ln -sf /Users/me/TestDirectory ./pdfs-output
这样一来，你的代码就可以用安全的相对路径来操作了，实际文件会被写入到链接指向的绝对路径下：
await page.pdf({
path: pdfs-output/${name}.pdf, // 实际写入 /Users/me/TestDirectory/
});
? 总结要点
回过头看，在 Puppeteer 中保存 PDF 到绝对路径，其实就几个核心原则，把握住就万无一失：
- ✅ 路径必须是合法的 POSIX 绝对路径字符串，比如 `/full/path/to/file.pdf`，干干净净，别加任何修饰。
- ✅ 务必提前创建父目录。用 `fs.mkdirSync(…, {recursive: true})` 一步到位，这是很多异步操作前的必备安全检查。
- ❌ 坚决禁止添加 `file://`、`https://` 或 `~` 这类前缀。记住，这里不是浏览器地址栏。
- ? 权限检查要先行。确保运行 Node 进程的用户对目标路径有写入权限。在 macOS/Linux 下，用 `ls -ld /目标路径` 看一眼权限位，心里就踏实了。
- ? 如果还不放心，不妨在开发阶段先用 `fs.writeFileSync(‘/tmp/test.pdf’， ‘test’)` 这样的小命令验证一下路径的可写性，排除环境问题。
把这些规范做到位，你就能在任何环境下，稳定、安全地把 Puppeteer 生成的 PDF 保存到指定的绝对路径了。
