Puppeteer 的 page.pdf() 方法不支持 file:// 协议前缀的路径，且直接传入绝对路径（如 /Users/.../file.pdf）可能因权限、工作目录或 Node.js 文件系统限制而失败；应使用标准 POSIX 绝对路径字符串（无协议），并确保目标目录存在且进程有写权限。
puppeteer 的 `page.pdf()` 方法不支持 `file://` 协议前缀的路径，且直接传入绝对路径（如 `/users/.../file.pdf`）可能因权限、工作目录或 node.js 文件系统限制而失败；应使用标准 posix 绝对路径字符串（无协议），并确保目标目录存在且进程有写权限。
在 Puppeteer 中生成 PDF 并保存到绝对路径是一个常见但易出错的操作。核心误区在于：page.pdf({ path: ... }) 的 path 选项不是 URL，而是 Node.js fs.writeFile() 兼容的本地文件路径——它不能带 file:// 前缀，也不接受波浪号 ~ 等 shell 展开符号。
✅ 正确做法：使用纯净的绝对路径（推荐）
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 saved 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()) 调试当前工作目录，避免相对路径歧义。
? 备选方案：符号链接（适合跨项目/权限受限场景）
若目标路径权限受限（如系统根目录），可创建符号链接将项目内子目录映射至目标位置：
# 在终端执行（需有目标目录写权限） ln -sf "/Users/me/TestDirectory" "./pdfs-output"
然后代码中只需使用安全的相对路径：
await page.pdf({
path: `pdfs-output/${name}.pdf`, // 实际写入 /Users/me/TestDirectory/
});
? 总结要点
- ✅ path 必须是合法的 POSIX 绝对路径字符串（如 /full/path/to/file.pdf）；
- ✅ 务必提前创建父目录（fs.mkdirSync(..., {recursive: true})）；
- ❌ 禁止添加 file://、http:// 或 ~ 等非文件系统语义前缀；
- ? 权限优先：确保运行 Node 进程的用户对目标路径有 write 权限（macOS 可通过 ls -ld /Users/me/TestDirectory 检查）；
- ? 开发时建议先用 fs.writeFileSync('/tmp/test.pdf', 'test') 验证路径可写性。
遵循以上规范，即可稳定、安全地将 Puppeteer 生成的 PDF 保存至任意绝对路径。
