可以直接安装的 Tampermonkey(油猴)脚本,无需构建、服务器或第三方 JS 库。
支持定时点击并返回、录制操作、每日或间隔采集多个值、自动追加到本地 CSV 文件、CSV 导出,以及元素定位诊断。任务、录制输入和采集历史保存在浏览器本地。
- 浏览器安装 Tampermonkey。
- 点击 安装最新版脚本,在油猴安装页确认安装。
- 刷新需要保活或采集的网页,右下角会出现「定时助手」。如未出现,检查油猴是否已启用并获准在该网站运行;Chromium 浏览器还需按油猴提示允许执行用户脚本。
若安装链接打开成代码,可点击油猴图标 →「添加新脚本」,删除默认代码,把仓库中 web-keeper.user.js 的全部内容复制进去并保存。已安装的用户可以在油猴管理面板检查更新,或再次打开安装链接更新脚本。更新后刷新目标网页。
脚本匹配普通 HTTP / HTTPS 网页,每个网站(协议 + 域名 + 端口)的任务独立保存,初始为暂停。也可以修改文件顶部的 @match,只在需要的网站上运行。脚本不会自动填写登录信息。
如果直接双击 demo/index.html,地址是 file:///...,当前脚本不会匹配。先在项目目录运行 node demo/server.cjs,再打开 **http://127.0.0.1:4173/**。演示页顶部会显示脚本加载状态,检测到脚本后也可以点击「打开定时助手」。
Edge 用户:在地址栏输入 edge://extensions,开启「开发人员模式」,确认 Tampermonkey 已启用且有当前网站的访问权限;如果扩展详情提供「允许用户脚本」开关,也可以按提示开启该开关。然后在油猴管理面板确认「网页保活与定时采集助手」已启用,刷新目标网页。执行权限说明见 Tampermonkey 官方 FAQ。
脚本执行后,油猴菜单中应有「打开网页定时助手」。如果有这个菜单但看不到按钮,可从菜单打开面板;如果菜单也没有,先检查页面地址、脚本是否安装/启用和扩展执行权限。
1.0.1 补充了普通 HTTP 页面下的 ID 兼容处理,并加强悬浮入口的样式隔离。
1.0.2 修复了 Ant 自定义下拉框的录制和回放:自动排除 active、selected 等状态类;点击选项时按完整文字匹配当前可见菜单,兼容旧任务中录制的 Ant 高亮项选择器。回放自定义下拉框还会发送鼠标按下/抬起事件,支持在 mousedown 打开的菜单。
1.0.3 在面板标题显示运行版本,并拆开元素定位失败的具体原因。点击和输入可匹配唯一可见元素,排除隐藏的同名副本;多个可见元素仍会停止。新录制优先采用 data-testid、name、aria-label 等属性,不使用 rc_select_ 等运行时生成 ID。
1.0.4 新增「运行环境」页签及油猴菜单入口,提供后台运行观察、Edge 活动网站列表和 Windows 电源设置指引。
1.0.5 新增「采集历史 → 自动保存到本地文件」,选择并授权一次后,每次采集自动追加到同一个 CSV 文件,支持刷新恢复、记录去重和失败后补写。
1.0.6 修复后台限速时任务内部阶段重复等待导致的过早超时:一次检查内推进已就绪的内部阶段,每次至多执行一个页面操作;为观测到的慢速检查提供固定、有限的执行余量。新增白名单已配置时的 Edge 强力计时器限速策略指引。
打开「定时助手 → 运行环境」,或从油猴菜单选择「运行环境与设置指引」。
- 可以自动观察: 页面可见或后台状态、浏览器报告的在线/离线状态、最长调度间隔,以及浏览器提供的冻结/恢复、此前丢弃记录。在线状态不代表目标网站实际可访问;前后台状态不能区分最小化、切换标签和锁屏。
- 无法直接读取或修改: Edge 的标签休眠白名单、节能开关和 Windows 的自动睡眠/休眠配置。运行环境页提供复制设置地址、复制本站地址和操作步骤。浏览器不允许网页直接打开
edge://设置页,应复制到地址栏打开。 - 手动确认: 设置完成后可勾选对应项目,确认时间保存在当前网站的油猴存储。界面明确标记为「用户确认(非自动验证)」,可随时取消。
- 后台实测: 点击「重新开始观察」,将浏览器最小化或锁屏至少 10 分钟,再返回检查。观察本身不会额外点击网页;原有已启用任务仍会执行。刷新或页面跳转后,当前页面的观察重新开始。
两次调度检查间隔达到 5 秒时,界面显示延迟提示;本站任务启用时也会记录警告日志(最多每 5 分钟一条调度延迟警告)。该间隔不能证明电脑休眠或某项设置有误,也可能来自页面繁忙或系统时钟变化。页面暂停期间无法发出提示,只能在恢复后记录。未出现延迟、没有冻结事件或已勾选确认,都不能保证未来准时运行。
Edge 指引:设置 → 系统和性能 → 性能 →「始终保持这些网站处于活动状态」,添加本站地址。Windows 指引:设置 → 系统 → 电源和电池 / 电源,检查运行任务时使用的供电模式下的自动睡眠与休眠设置,并保持浏览器、标签页及网络连接。详细说明见 微软 Edge 性能设置 与 Windows 电源设置。
这不能仅凭日志认定为标签休眠。Chromium 在 Windows 锁屏时将窗口判为被遮挡,会把窗口里的前台标签按后台标签处理,可能停止渲染并限制 JavaScript。参见 Chromium 窗口遮挡说明。
Edge 另有 IntensiveWakeUpThrottlingEnabled 策略,控制页面在后台超过 5 分钟后的强力计时器限速,启用时每分钟最多执行一次。反复出现约 60 秒的检查间隔符合该行为,但也可能有其他原因。白名单和关闭节能模式并不能据此证明该策略已关闭。参见 微软策略文档。
可按微软文档由你或管理员将该策略设置为禁用:安装 Edge 管理模板的环境中,在「管理模板 → Microsoft Edge → 控制 IntensiveWakeUpThrottling 功能」选择「已禁用」。对应注册表策略路径为 SOFTWARE\Policies\Microsoft\Edge,值名 IntensiveWakeUpThrottlingEnabled,类型 REG_DWORD,禁用值为 0。这是整个 Edge 的策略,可能增加后台耗电;公司管理的电脑应由管理员处理。
配置后在地址栏打开 edge://policy,重新加载策略,确认该项为 false 且状态正常。没有该项表示未配置,由浏览器内部逻辑控制,不能当作已禁用。保存其他网页工作,完全退出并重新启动 Edge,再进入目标网站重新测试;只刷新网页不足以保证所有进程使用新策略。脚本的「运行环境」提供说明和复制策略检查地址,但无法读取或修改浏览器策略。
1.0.6 的调度兼容会减少无须等待的内部阶段开销,并按本轮观察到的检查间隔增加有限的执行余量;配置的步骤等待、返回等待和元素超时仍保留,任务总截止时间锚定本轮开始,长时间暂停后仍会终止过期任务。这能减少限速时脚本自身的过早失败,实际操作仍可能晚于计划。
油猴不能强制唤醒冻结或被丢弃的标签页,也不能唤醒已休眠的电脑。 页面冻结时计时器和其他回调暂停;屏幕 Wake Lock 仅适用于可见、活动页面,转入后台可被释放,不能作为锁屏执行保证。见 页面生命周期说明 与 Screen Wake Lock 说明。网站自身也可能在后台停止刷新,或要求可信用户操作;调整浏览器限速不能保证网站一定续期。
先查看面板标题是否是当前脚本版本,安装更新后必须刷新目标网页。进入原任务编辑,在失败步骤点「检查定位」,会显示可复制的诊断:脚本版本、步骤类型、当前页面、每层选择器的全部/可见匹配数量,以及具体失败原因。检查定位不会点击或填写页面,也不会替你打开目标页面;应在该步骤预期的页面状态下检查。
- 匹配 0 个:通常是页面还没到达、选择器已变化、录制了临时 ID 或元素不在当前文档。只需在正确页面重新选择该步骤的元素,不必重录整条任务。
- 全部隐藏:目标区域或菜单尚未展开。
- 多个可见元素:选择器需要加上稳定的父容器或属性,不能取第一个匹配猜测。
- 被禁用:等待页面加载或先完成必要条件。
运行失败时,「日志」也会保存该步的定位诊断。若仍无法定位,请复制失败步骤的诊断,以及该步是“打开下拉框”还是“选择选项”,以便按实际元素修正。
例如 li.ant-select-dropdown-menu-item.ant-select-dropdown-menu-item-active 只代表当时高亮的行,下一次可能变成其他省份。请安装 1.0.2 或更新版本,打开原任务编辑,在对应点击步骤的「下拉选项文字(完整匹配)」中填写 甘肃,保存后试运行。旧任务若已记录完整选项文字,可直接按文字回放;若文字不完整或错误,应修正该字段或重新选择元素。
该步骤前必须有「打开对应下拉框」的点击操作。回放会等待选项出现,并只点击可见且文字完全相同的唯一选项;匹配不到、匹配多个或选项被禁用时,本轮停止后续采集并显示原因。不会通过列表位置或高亮状态猜测选项。当前支持 Ant 的常见新旧 Select 菜单、role="option" 以及 Element UI 下拉项;虚拟列表里尚未渲染的选项需要录制搜索操作,使目标选项出现在菜单中。
- 登录目标网站,进入要操作的页面。
- 打开「定时助手」→「+ 保活任务」。
- 点击「点选点击元素」,鼠标移到按钮、链接上,出现蓝色框后点击选中。点选这一下不会执行页面的普通点击操作;Esc 可取消。
- 设置任务名称和执行间隔,例如每 5 分钟。最小间隔为 5 秒。
- 设置返回等待,例如 3 秒,并选择返回方式。
- 点击「保存任务」→「启用本站」。也可以先点「立即执行」检查结果。
每轮执行会先打开保存的起始地址,再按步骤操作。返回地址是本轮执行开始前的地址。
- 历史后退:尽量后退到执行前的历史位置;无法返回时用原地址兜底。普通页面跳转和改变地址的 SPA 跳转均可使用。
- 打开执行前地址:直接打开原地址,页面会重新加载。
- 不返回:停留在操作后的页面。
如果按钮只打开弹窗而不改变地址,历史后退不能关闭弹窗。可以把关闭弹窗的点击也加入步骤,或者选择不返回。
只读当前页面:
- 点击「+ 采集任务」。
- 点击「添加采集值」,选择页面上的数值元素。
- 把「数值 1」改成「激活量」。重复添加「新增用户」「订单数」等其他值。
- 选择「每天固定时间」,例如 09:00,或改为间隔计划。
- 保存并启用本站。
需要先进入报表、设置筛选条件:
- 在流程的起始页面创建采集任务,点「录制操作」。
- 按正常使用顺序点击菜单、按钮、链接,填写查询条件,切换下拉框或复选框。
- 到达需要的报表后,点录制工具条上的「采集值」,选中一个数值。可以在不同页面、不同阶段多次添加。
- 如报表异步加载较慢,用「添加等待」插入等待步骤,或完成录制后调大某一步的「执行前等待」。
- 点「完成录制」,修改每个值的名称,调整计划,保存任务。
- 用「立即执行」试跑。结果出现在「采集历史」,执行失败原因在「日志」。
采集步骤可以穿插在点击和输入步骤之间,因此一条任务可以读取多个页面、多个值。步骤可上移、下移、删除,选择器和录制的输入值也可以编辑。再次录制会继续追加步骤。
读取方式:
| 方式 | 用途 |
|---|---|
| 自动 | 输入框、下拉框读取表单值;其他元素读取文本 |
| 文本内容 | 读取元素的文本(含子元素) |
| 表单值 | 读取输入框、下拉框、复选框的值 |
| 指定属性 | 例如 data-count、title |
「正则提取规则」可留空。填写 ([0-9,]+) 可以从「激活量:1,234 人」中提取 1,234;有捕获组时取第一个捕获组,否则取整个匹配。规则不需要两侧的 /,也不需要 g 标记。
选择器匹配多个元素时会报错,避免采集错误位置。开放 Shadow DOM 的选择器用 >>> 分隔每一层;可以通过重新点选修复页面改版后失效的元素。
点选或录制会记住步骤所在页面,回放时先等待进入对应路径和 hash,避免在页面切换尚未完成时操作旧页面;比较时忽略查询参数和末尾斜杠。需要跨查询参数区分报表时,应通过录制筛选操作或起始地址设置参数。「执行页面」也可手动修改或清空。
- 任务和历史保存在油猴本地存储,刷新或重启浏览器后仍保留。草稿、录制状态和执行进度保存在当前标签的会话存储,同站整页跳转后可继续。
- 每个网站由一个标签页执行任务,多个任务按到期顺序排队。点「启用本站」或「立即执行」会把执行标签切到当前标签;原执行标签会停止后续步骤。执行标签关闭或前往另一个普通网站后,其他打开的同站标签可接管。
- 间隔从上一轮结束后计算;每日计划使用电脑本地时间。网站暂停时不自动执行任务,但「立即执行」仍可手动执行。
- 页面恢复运行后,错过的任务补执行一次,不连续重放每个错过的周期。
- 找不到元素、选择器不唯一或元素禁用时,会等待配置的超时时间;失败后记日志,并尽量返回原地址。已成功读取的部分结果会保留。
- 采集历史最多保存 5,000 条,日志最多 200 条。可导出全部采集历史为带 UTF-8 BOM 的 CSV;时间列是带
Z的 UTC 时间,界面显示本地时间。CSV 中潜在的表格公式前缀会加单引号。 - 「导出配置 / 导入配置」备份和恢复当前网站的任务。导入只接受相同网站的配置,按任务 ID 更新或追加;不会删除未包含的任务。
- 更新脚本并刷新目标网页,打开「定时助手 → 采集历史」。
- 在「自动保存到本地文件」中点击「选择 CSV 文件并启用」。
- 在浏览器弹出的文件选择框中选择保存目录和文件名。请使用新的空 CSV 文件,或本功能之前创建的文件;非空的其他文件和手动导出的旧格式 CSV 会被拒绝,不会覆盖。
- 按浏览器提示授权写入。当前采集历史会补写进去,之后每条采集结果自动追加到同一个文件,无需再次点击导出。
文件包含 记录ID、采集时间、任务、值名称、值、原始内容、页面地址 七列,使用带 UTF-8 BOM 的 CSV,可用 Excel 打开。时间列为 UTC 时间。记录 ID 用于去重;即使刷新、重试或打开多个同站标签,已经写入的记录也不会再次追加。文件中的旧记录不会随浏览器历史的 5,000 条上限删除。多个值分别保存为多条记录。
面板显示文件名、已保存条数和上次写入时间,支持「立即同步文件」「停止自动保存」「更换保存文件」。首次连接新文件时会补写当前历史;因此更换文件也会包含当前仍保留的历史记录。
- 浏览器条件: 使用新版桌面 Edge / Chrome,目标页面需要 HTTPS;本机
localhost/127.0.0.1演示也可使用。普通 HTTP 页面或未提供文件访问能力的浏览器会说明原因,仍可手动导出。 - 首次需要用户选择: 浏览器不允许脚本直接按任意本地路径写入,必须由你通过文件选择框选择并授权。浏览器通常只向网页提供文件名,面板不会显示完整路径。该能力见 File System Access 官方说明。
- 刷新与重启: 同站刷新、页面跳转后自动恢复选定文件;重启浏览器或撤销权限后可能需要点击「重新授权并重试」。后台采集不会自动弹出授权窗口。清除本站存储、换浏览器或更换网站后,需要重新选择文件;保存位置不包含在导出的任务配置中。
- 写入失败: 文件被占用、移走、权限失效或内容损坏时会提示原因,采集历史仍保留。解决问题后重新授权或立即同步,会补写仍在历史中的记录。失败期间超过 5,000 条而被淘汰的历史无法补写,请及时处理保存提示。
- 文件管理: 建议不同网站使用不同文件。用 Excel 编辑或手动修改 CSV 前先停止自动保存,编辑完成并关闭文件后再启用。脚本只向格式正确的文件追加,失败时中止写入,避免留下半条记录。文件被外部编辑后可点击「立即同步文件」重新检查。
自动保存与任务开关独立:停止任务后仍可同步已有历史;停止自动保存不会停止采集。后续步骤中的整页跳转会等待当前采集结果保存结束。浏览器关闭或电脑休眠期间无法采集、写入文件。
- 浏览器和至少一个目标网站标签需要保持打开。 浏览器关闭、系统休眠、标签被丢弃时不能执行。后台标签计时可能被浏览器延迟,恢复后才补执行。
- 点击能否续期由网站决定。有些站点只认可服务器请求,或要求可信的用户点击;模拟点击可能无法保活,也不能绕过服务器的强制登录期限。先用「立即执行」确认选中的操作会产生实际活动。
- 录制支持普通点击、表单输入、同站页面跳转。浏览器工具栏的后退、键盘快捷键、拖拽、上传、验证码和弹出的新窗口不作为操作录制。需要回退时录制页面内的返回链接;回放普通链接时会尽量使用当前标签。
- 录制时单次自然操作间隔最多记为 60 秒;需要更长等待时,插入「等待」步骤或编辑等待时长。
- 当前版本不进入 iframe,不读取封闭 Shadow DOM,也不支持跨域流程。若站点的点击处理器把页面重定向到另一域名,执行不能在那里继续;回到原站后会恢复检查或超时结束。
- 密码、文件和隐藏输入框不录制;密码和文件输入框不能采集。其他录制的查询文本、步骤和采集结果只在本机保存,导出配置会包含普通录制输入。
- 页面复杂事件、框架校验或动态选择器可能需要调整步骤;建议先试跑一次。异步报表如果已经存在旧值,应明确加入等待,脚本不能判断业务数据是否更新完成。
demo/index.html 是可用于点选、录制和采集的测试页面,需要通过本地 HTTP 服务访问(演示包含 /activity、/reports 路由)。
在项目目录执行 node demo/server.cjs,浏览器打开 http://127.0.0.1:4173 即可演示。服务还提供 http://127.0.0.1:4173/web-keeper.user.js 安装地址,已装油猴的浏览器可从此地址安装脚本。按 Ctrl+C 结束服务。
基础逻辑测试仅依赖 Node.js:
node --test tests/core.test.cjs浏览器集成测试使用 Playwright,创建临时本地 HTTP 服务并在 Chromium 中验证实际操作。测试模拟了油猴的存储与标签页 API;实际油猴安装后的表现还需在目标网站确认。
# 已安装 Node.js/npm 的开发环境中
npm install --no-save playwright
npx playwright install chromium --only-shell
node tests/browser.test.cjs
node tests/auto-save.browser.test.cjs
node tests/background.browser.test.cjs也可以通过环境变量 PLAYWRIGHT_MODULE 指定已有 Playwright 模块的绝对路径,PLAYWRIGHT_BROWSERS_PATH 指定浏览器缓存。测试截图和 CSV 保存到 test-results/。
自动保存测试使用 Chromium 的真实文件句柄、文件写入流、IndexedDB 和 Web Locks,文件选择器替换为返回浏览器私有文件系统(OPFS)的测试句柄;权限失效和占用通过失败注入验证。覆盖采集后写入、整页跳转前保存、刷新恢复、重试补写、多标签去重、不相关/损坏文件保护,以及不支持该 API 时的手动导出。系统文件选择框及实际油猴权限仍需在安装后的浏览器中确认。
后台测试使用真实 DOM 点击,模拟每分钟一次的助手检查和固定测试时钟,验证多步骤执行、配置等待、定位失败及长时间暂停后终止任务。它不验证实际 Windows 锁屏、Edge 策略生效或目标网站能否保活,安装更新后仍需做后台实测。
油猴 API 参考:Tampermonkey 官方文档。
git clone https://github.com/mannixS/web-keeper-userscript.git
cd web-keeper-userscript
node --test tests/core.test.cjs
node demo/server.cjs代码入口是 web-keeper.user.js;demo/ 提供演示页面;tests/ 包含基础逻辑与浏览器集成测试。修改录制、定位或回放逻辑时,请同时运行相关浏览器测试。浏览器缓存、日志和测试生成文件不会提交到仓库。
问题反馈请提交到 Issues,提供脚本版本、复现步骤和定位诊断。分享前请删去网址中的敏感路径、业务数据和录制输入;登录凭据和网站导出配置不应放进公开问题或仓库。
本项目采用 MIT License。