PageVoyager 是一个面向网页探索、页面留档和自动截图的命令行工具。
你输入一个 URL，它会像“巡航器”一样自动进入站点、探索可访问页面、执行有限且安全的页面展开操作，并为每个访问到的页面保存整页截图，同时生成结构化报告。
- 项目名：
PageVoyager - 中文名：
页航 - 含义：像一艘在网页空间中巡航的航行器，自动访问页面、记录路径、沉淀页面快照
- 适用场景：竞品采集、网站留档、页面审计、资料归档、手工测试辅助
- 基于
Playwright + Chromium自动浏览网页 - 默认仅探索与起始 URL 相同
hostname的页面 - 自动处理常见 cookie 弹窗、展开部分折叠区、尝试打开导航入口
- 遇到登录页时，在可见浏览器模式下暂停，等待手动登录后继续
- 为每个已访问页面保存 1 张整页截图
- 生成
report.json和run.log，便于检索、排错和二次分析
安装依赖和浏览器：
npm install
npm run install:browsers开发模式运行：
npm run dev -- --url https://example.com构建后运行：
npm run build
node dist/cli.js --url https://example.com如果要作为全局命令使用：
npm run build
npm link
page-voyager --url https://example.com抓取一个站点并限制规模：
node dist/cli.js \
--url https://example.com \
--max-pages 20 \
--max-depth 2后台无头运行：
node dist/cli.js \
--url https://example.com \
--headless指定输出目录：
node dist/cli.js \
--url https://example.com \
--output ./runs/example-audit扩展允许探索的 host：
node dist/cli.js \
--url https://www.example.com \
--allowed-hosts www.example.com,docs.example.com--url, -u：起始 URL，必填--output, -o：输出目录--max-pages：最多访问多少页--max-depth：最大探索深度，0表示只抓首页--allowed-hosts：允许继续探索的 host 白名单，逗号分隔--headless：无头模式运行--headed：显式开启可见浏览器，默认模式--login-wait：检测到登录页后暂停等待，默认开启--no-login-wait：检测到登录页时不暂停--navigation-timeout：页面导航超时，单位毫秒--stable-wait：页面额外稳定等待时间，单位毫秒
默认会在 runs/ 下生成一次任务目录：
runs/example-com-2026-03-31T01-00-00-000Z/
screenshots/
0001-home.png
0002-products.png
report.json
run.log
其中：
screenshots/：页面截图report.json：结构化任务报告run.log：执行日志
report.json 重点字段包括：
- 请求 URL 与最终 URL
- 页面标题
- 页面深度与来源页
- 截图路径
- 登录页检测结果
- 自动交互记录
- 发现链接数与实际入队数
- 错误信息与耗时
默认使用可见浏览器模式运行。如果检测到登录页，并且终端可交互，程序会：
- 保持浏览器停留在当前页面
- 等你手动完成登录
- 回到终端按回车
- 继续后续探索
如果使用 --headless，则不会等待手动登录。
PageVoyager 的目标是“探索与留档”，不是高风险自动化操作工具。因此它默认会避免执行以下动作：
- 删除
- 支付
- 购买
- 提交
- 发送
- 退出登录
同时它也会忽略明显不是网页的链接，例如图片、PDF、压缩包、音视频和文档下载链接。
- 产品与命名说明：
docs/branding.md - 架构与实现说明：
docs/architecture.md
- 支持逐屏截图模式
- 支持子域名白名单配置文件
- 支持 Cookie / Session 持久化
- 支持 HTML 报告导出
- 支持队列并发和断点续跑