Puppeteer 的 page.pdf() 不支持 file:// 协议或非法绝对路径写入，必须使用合法的本地文件系统绝对路径（如 /Users/xxx/...），且需确保目录存在、权限充足；推荐采用相对路径 + 项目根目录解析，或符号链接方案规避权限与路径解析问题。
puppeteer 的 `page.pdf()` 不支持 `file://` 协议或非法绝对路径写入，必须使用合法的本地文件系统绝对路径（如 `/users/xxx/...`），且需确保目录存在、权限充足；推荐采用相对路径 + 项目根目录解析，或符号链接方案规避权限与路径解析问题。
在使用 Puppeteer 将 HTML 转换为 PDF 时，一个常见误区是误以为 page.pdf({ path: '...' }) 支持 file:// URL 格式（如 file:///Users/.../doc.pdf）。实际上，该 path 选项仅接受标准的本地文件系统路径（POSIX 或 Windows 风格的绝对/相对路径），且 Puppeteer 会直接调用 Node.js 的 fs.writeFile 写入——因此传入 file:// 前缀会导致路径被当作无效 URI 处理，最终触发 ENOENT 错误（如 open 'file://Users/...' failed）。
✅ 正确做法：使用合法绝对路径（推荐）
确保目标目录已存在，并使用 path.resolve() 构建绝对路径：
import * as path from 'path';
import * as fs from 'fs';
// ✅ 正确：使用 path.resolve 生成真实绝对路径
const outputDir = '/Users/me/TestDirectory';
const pdfFileName = `${name}-${Math.round(Math.random() * 50)}.pdf`;
const pdfPath = path.resolve(outputDir, pdfFileName);
// 创建目录（避免 ENOENT 因父目录不存在）
if (!fs.existsSync(outputDir)) {
fs.mkdirSync(outputDir, { recursive: true });
}
await page.pdf({
format: 'A4',
path: pdfPath, // ← 直接传入 /Users/me/TestDirectory/xxx.pdf
printBackground: true,
});
⚠️ 注意事项：
- 目录必须提前存在或手动创建（fs.mkdirSync(..., { recursive: true })）；
- 运行 Node.js 进程的用户需对目标路径有写入权限（macOS 上尤其注意 ~/ 展开问题）；
- ❌ 禁止使用 ~/TestDirectory/xxx.pdf（Node.js 不自动展开 ~）；应改用 path.join(os.homedir(), 'TestDirectory', ...)；
- ❌ 禁止添加 file:// 前缀——这是浏览器资源协议，不适用于文件系统写入。
? 替代方案：符号链接（Symbolic Link）
若目标路径跨项目或权限受限，可将外部目录软链至项目内，再用相对路径保存：
# 终端执行（一次配置） ln -sf "/Users/me/TestDirectory" ./pdfs
// Puppeteer 中直接使用相对路径
await page.pdf({
format: 'A4',
path: `pdfs/${name}-${Date.now()}.pdf`, // 自动写入软链指向的真实目录
printBackground: true,
});
该方式无需额外权限配置，且路径可移植性强。
? 备选方案：生成后移动文件
若以上均不可行（如 CI 环境限制），可在 PDF 生成后用 fs.rename() 或 cp 命令迁移：
const tempPdf = path.join(process.cwd(), 'temp.pdf');
await page.pdf({ path: tempPdf, format: 'A4' });
// 移动到绝对路径
const finalPath = path.resolve('/Users/me/TestDirectory', `${name}.pdf`);
await fs.promises.rename(tempPdf, finalPath);
✅ 总结
| 方案 | 适用场景 | 关键要点 |
|---|---|---|
| path.resolve() 绝对路径 | 开发/测试环境，可控目录权限 | ✅ 显式创建目录、✅ 验证用户权限、❌ 勿加 file:// |
| 符号链接 | 需跨目录保存、权限受限 | ✅ 一次配置长期有效、✅ 路径语义清晰 |
| 生成后迁移 | 临时方案或 CI/CD 流水线 | ✅ 解耦生成与存储逻辑、✅ 需处理异步重命名 |
始终优先使用 path.resolve() 构建路径，并配合 fs.existsSync() 和 mkdirSync({ recursive: true }) 做防御性检查——这是最健壮、最符合 Node.js 文件 I/O 规范的实践。
