Playwright Download Fix

Playwright 下载的文件名是 UUID 而不是原始文件名？这个 skill 帮你自动修复这个问题。

问题

当使用 Playwright 下载文件时，经常会遇到：

• 浏览器中显示的文件名是 f63a84ec-abd1-48fa-a748-11ebeca07935（UUID）
• 但在真实 Chrome 中下载的文件名是正确的，比如 MVIMG_20250706_131754.jpg

原因

1. Playwright 默认下载到临时目录，使用 UUID 作为临时文件名
2. 网站检测到自动化工具，返回了临时文件名
3. 需要拦截 download 事件并使用 suggestedFilename() 获取原始文件名

解决方案

这个 skill 提供了一个 DownloadHelper 模块，自动监听下载事件并用正确的文件名保存文件。

🚀 快速启动

方式 1: 使用 pw-start 命令（推荐）

确保快捷命令已添加到 shell 配置文件：

\\\`bash

添加到 ~/.zshrc（首次使用）

echo "alias pw-start='cd ~/.openclaw-autoclaw/workspace && node pw-start.js'" >> ~/.zshrc

source ~/.zshrc

使用

pw-start # 打开默认页面（智联招聘）

pw-start https://example.com # 打开指定 URL

\\\`

每次运行都会自动加载 DownloadHelper skill 并显示配置信息：

========================================
📋 配置信息
========================================
🌐 User-Agent: 真实 Chrome (macOS)
📂 下载目录: /Users/allen/downloads
🔍 调试模式: 开启
========================================

方式 2: 直接运行独立脚本

\\\`bash

cd ~/.openclaw-autoclaw/skills/playwright-download-fix

node standalone-script.js

\\\`

方式 3: 在现有项目中集成模块

\\\`bash

复制模块到项目

cp ~/.openclaw-autoclaw/skills/playwright-download-fix/download-helper.js .

\\\`

然后在脚本中使用：

\\\`javascript

const { chromium } = require('playwright');

const DownloadHelper = require('./download-helper');

async function myScript() {

const browser = await chromium.launch({ headless: false });

const context = await browser.newContext({

acceptDownloads: true,

});

const page = await context.newPage();

// 初始化下载助手

const helper = new DownloadHelper(page, {

downloadDir: '~/downloads',

debug: true

});

const downloadDir = await helper.setup();

console.log(\📂 下载目录: \${downloadDir}\);

// 你的自动化代码...

await page.goto('https://example.com');

await page.click('#download-button');

// 获取下载的文件列表

console.log('下载的文件:', helper.getDownloadedFiles());

await browser.close();

}

myScript();

\\\`

📋 启动环境与要求

系统要求

• 操作系统: macOS / Linux / Windows
• Node.js: >= 14.x
• Playwright: 已安装

依赖安装

\\\`bash

安装 Playwright（如果未安装）

npm install playwright

安装浏览器

npx playwright install chromium

\\\`

启动条件

1. 下载目录权限: 确保对下载目录（默认 ~/downloads）有写权限
2. 浏览器缓存: 首次运行会下载 Chromium（约 170MB）
3. 内存要求: 至少 4GB 可用内存
4. 网络连接: 部分网站需要网络访问

启动配置

默认配置（可在 pw-start.js 中修改）：

反自动化检测

为了更接近真实浏览器，默认启用以下配置：

\\\`javascript

const context = await browser.newContext({

userAgent: realChromeUA,

locale: 'zh-CN',

timezoneId: 'Asia/Shanghai',

bypassCSP: true,

javaScriptEnabled: true,

acceptDownloads: true,

});

\\\`

DownloadHelper API

构造函数

\\\`javascript

new DownloadHelper(page, options)

\\\`

参数：

• \page\ (Page) - Playwright page 实例
• \options\ (Object) - 配置选项

- \downloadDir\ (string) - 下载目录路径，支持 \~\ 符号，默认 \~/downloads\

- \debug\ (boolean) - 是否显示调试信息，默认 \false\

方法

setup()

初始化下载监听器，创建下载目录（如果不存在）。

\\\`javascript

const downloadDir = await helper.setup();

\\\`

返回： 下载目录的绝对路径

getDownloadedFiles()

获取本次会话中下载的所有文件路径列表。

\\\`javascript

const files = helper.getDownloadedFiles();

console.log('下载的文件:', files);

\\\`

返回： 文件路径数组

clearHistory()

清空下载历史记录。

\\\`javascript

helper.clearHistory();

\\\`

dispose()

移除下载监听器。

\\\`javascript

helper.dispose();

\\\`

完整示例

示例 1: 下载单个文件

\\\`javascript

const { chromium } = require('playwright');

const DownloadHelper = require('./download-helper');

async function downloadSingle() {

const browser = await chromium.launch({ headless: false });

const context = await browser.newContext({

acceptDownloads: true,

});

const page = await context.newPage();

const helper = new DownloadHelper(page, {

downloadDir: '~/downloads',

debug: true

});

await helper.setup();

await page.goto('https://example.com');

await page.click('#download-button');

await page.waitForTimeout(3000);

const files = helper.getDownloadedFiles();

console.log('下载的文件:', files);

await browser.close();

}

downloadSingle();

\\\`

示例 2: 批量下载

\\\`javascript

const { chromium } = require('playwright');

const DownloadHelper = require('./download-helper');

async function downloadMultiple(urls) {

const browser = await chromium.launch({ headless: false });

const context = await browser.newContext({ acceptDownloads: true });

const page = await context.newPage();

const helper = new DownloadHelper(page, {

downloadDir: '~/downloads',

debug: true

});

await helper.setup();

for (const url of urls) {

await page.goto(url);

await page.click('.download-link');

await page.waitForTimeout(2000);

}

console.log(\共下载 \${helper.getDownloadedFiles().length} 个文件\);

await browser.close();

}

downloadMultiple(['url1', 'url2', 'url3']);

\\\`

示例 3: 智联招聘下载简历

\\\`javascript

const { chromium } = require('playwright');

const DownloadHelper = require('./download-helper');

async function downloadResumes() {

const browser = await chromium.launch({ headless: false });

const context = await browser.newContext({

userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36',

acceptDownloads: true,

});

const page = await context.newPage();

const helper = new DownloadHelper(page, {

downloadDir: '~/downloads',

debug: true

});

await helper.setup();

// 导航到搜索页面

await page.goto('https://rd6.zhaopin.com/app/search');

// 手动登录...

// 搜索候选人并下载简历

// ...

await browser.close();

}

downloadResumes();

\\\`

工作原理

1. 监听下载事件：通过 \page.on('download', ...)\ 监听所有下载
2. 获取原始文件名：使用 \download.suggestedFilename()\ 获取服务器返回的真实文件名
3. 保存到指定目录：用正确的文件名保存到用户指定的目录
4. 追踪下载历史：记录所有下载的文件路径，方便后续处理

故障排除

问题 1: 下载的文件名仍然是 UUID

可能原因：

• 网站检测到了自动化工具
• User-Agent 不够真实
• 缺少必要的请求头

解决方案：

1. 使用更真实的 User-Agent
2. 添加更多请求头
3. 考虑使用 \puppeteer-extra-plugin-stealth\
4. 连接到真实的 Chrome 实例（CDP）

\\\`javascript

// 连接真实 Chrome

const browser = await chromium.connectOverCDP('http://localhost:9222');

\\\`

问题 2: 文件下载失败

可能原因：

• 未设置 \acceptDownloads: true\
• 下载目录无写权限
• 网络问题

解决方案：

\\\`javascript

// 1. 确保设置 acceptDownloads

const context = await browser.newContext({

acceptDownloads: true, // 必须设置

});

// 2. 检查目录权限

fs.accessSync(downloadDir, fs.constants.W_OK);

// 3. 查看 debug 输出

const helper = new DownloadHelper(page, { debug: true });

\\\`

问题 3: 文件保存位置不对

可能原因：

• \downloadDir\ 配置错误
• 相对路径解析问题

解决方案：

\\\`javascript

// 使用绝对路径

const helper = new DownloadHelper(page, {

downloadDir: '/Users/yourname/Downloads', // 绝对路径

});

// 或使用 ~ 符号

const helper = new DownloadHelper(page, {

downloadDir: '~/downloads', // 会自动解析为用户主目录

});

\\\`

问题 4: pw-start 命令未找到

解决方案：

\\\`bash

添加快捷命令

echo "alias pw-start='cd ~/.openclaw-autoclaw/workspace && node pw-start.js'" >> ~/.zshrc

重新加载配置

source ~/.zshrc

或重启终端

\\\`

配置文件说明

pw-start.js

主启动脚本，位于 \~/.openclaw-autoclaw/workspace/pw-start.js\

可配置项：

\\\`javascript

const CONFIG = {

userAgent: '...', // 自定义 User-Agent

locale: 'zh-CN', // 语言

timezoneId: 'Asia/Shanghai', // 时区

downloadDir: '~/downloads', // 下载目录

debug: true, // 调试模式

defaultUrl: '...' // 默认 URL

};

\\\`

standalone-script.js

独立运行脚本，位于 \~/.openclaw-autoclaw/skills/playwright-download-fix/standalone-script.js\

特点：

• 默认打开智联招聘搜索页
• 完整的下载事件监听

download-helper.js

核心模块，可复制到任何项目使用。

使用场景

场景 1: 智联招聘下载简历

\\\`bash

pw-start

浏览器自动打开智联招聘

手动登录后下载简历

文件自动保存到 ~/downloads

\\\`

场景 2: 任何需要下载的网站

\\\`bash

pw-start https://example.com

在浏览器中操作

下载的文件会自动用正确的文件名保存

\\\`

场景 3: 开发测试

\\\`bash

pw-start http://localhost:3000

测试本地开发环境的下载功能

\\\`

场景 4: 批量下载任务

在自动化脚本中集成 \DownloadHelper\，实现批量下载。

常见问题

Q: 如何查看下载的文件？

\\\`bash

ls ~/downloads

\\\`

Q: 支持其他浏览器吗？

当前仅支持 Chromium，但可以通过修改 \pw-start.js\ 使用 Firefox 或 WebKit：

\\\`javascript

const { firefox } = require('playwright');

const browser = await firefox.launch();

\\\`

相关文件

• \download-helper.js\ - 核心下载处理模块
• \standalone-script.js\ - 独立运行脚本
• \pw-start.js\ - 快速启动脚本（位于 workspace）
• \example.js\ - 使用示例
• \README.md\ - 快速指南

许可

MIT