只有持续通过的测试套件才有意义。你的结账流程今天运行正常，但可能在凌晨 2 点某个依赖项发布了破坏性变更，或者证书在周末过期，又或者配置漂移导致支付接口在周日宕机。你往往是从愤怒的客户那里得知消息，而不是通过测试运行。解决办法既枯燥又可靠：按计划运行 API 测试，无需人工点击按钮，并在出现问题时第一时间收到通知。
Apifox 内置的“定时任务”功能正是为此设计的。你可以将其指向已构建的测试场景，设置执行频率，选择运行机器，并配置告警。本指南将如实介绍所有相关内容，包括目前的限制。如果你是第一次对线上接口进行无人值守检查，我们的 API 监控入门指南提供了更广泛的背景信息，而 Apifox 定时任务文档 则是 UI 操作的权威参考。
在开始之前请注意：定时任务功能目前标记为 Beta 版，你的账户可获得的精确定时任务运行次数取决于你的订阅计划。在阅读本文时请留意这两点。
AI Coding 交流群
如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。
定时任务的作用（以及与定时抓取工具的区别）
Apifox 中的定时任务按循环周期运行一个或多个已保存的测试场景。想象一下跨核心 API 的夜间回归测试、每隔几小时对预发环境进行的冒烟测试，或者周末的健康扫描。任务会记住要运行哪些场景、访问哪个环境、多长时间触发一次、由哪台机器执行工作，以及失败时通知谁。
如果你曾看到“定时任务”这个词用于网页抓取或数据收集，那是另一回事。这个功能不是关于定时爬取网页。它位于“自动化测试”模块内，用于驱动你的接口用例：断言、链式请求、提取变量等等。其输出是关于你的 API 契约的通过或失败报告，而不是抓取的数据集。
这种区别很重要，因为它改变了你的配置内容。你不需要编写选择器或爬虫规则。你只需选择现有的测试场景，并告诉 Apifox 何时何地运行它们。
开始之前：配置自托管 Runner
这里有一个容易让人困惑的前提条件。要运行定时任务，你首先需要配置一个自托管 Runner。文档对此有明确说明。
Runner 是执行测试套件的机器。当定时任务触发时，Apifox 不会在你的桌面客户端中运行请求；它会将工作交给您选择的 Runner，套件中的每个请求都会从那台机器发出。CI 机器、小型的常驻服务器或专用的虚拟机都可以很好地胜任。无论你选择什么，都要保证它在所需的时间表上保持开启且可达。
Runner 目标字段提供两个选择：标记为“即将推出”的 Apifox 云端，或是自托管 Runner。由于 Apifox 云端尚未可用，自托管 Runner 是目前唯一可行的选项。在其正式发布前，请不要围绕云端执行进行规划。
由于请求源自 Runner 的机器，其网络环境会影响你的结果。位于企业 VPN 背后、不同地域或受防火墙保护的子网中的 Runner，看到的响应可能与你笔记本电脑上的不同。这通常正是你在进行真实监控时想要的，但当定时运行的结果与本地运行时不一致，这一点值得注意。
逐步指南：创建定时任务
注册 Runner 后，剩下的操作都在客户端中进行。以下运行的示例是一个针对电商 API 的夜间回归套件，涵盖了用户注册、产品列表、购物车以及由 Stripe 支持的结账功能。
1. 在自动化测试模块中打开定时任务
在 Apifox 客户端中打开“自动化测试”模块。在测试目录树中，点击“定时任务”以查看和管理项目中的所有定时任务。整个项目中的所有任务都会显示在“定时任务”部分下，因此这是你查看正在运行的内容及其时间的统一入口。
2. 创建任务
点击“新建”以创建一个新的定时任务。你也可以在这里创建一个目录来对相关任务进行分组，这在你拥有针对预发和生产环境，或不同服务的独立套件时非常方便。
给任务设定一个清晰的任务名称和描述。这些信息是为了区分任务并解释其目的，以便未来的你在不打开它的情况下，就能知道“Nightly regression, prod”究竟涵盖了哪些内容。每个任务还都有一个启用/禁用开关，目录树中的任务可以随时开启或关闭。
3. 选择要运行的测试场景
在“测试场景”下，挑选一个或多个要包含的场景。对于这个电商示例，你可能会选择“Signup and login”、“Browse and add to cart”和“Checkout with Stripe test card”，以便用单一任务覆盖整个关键路径。
每个场景都可以带有自己的执行设置：环境、测试数据、循环次数、延迟，以及是否保存请求历史和响应。如果你不想逐个调整，可以开启“使用相同执行配置”，将单一的运行时配置一次性应用到所有选定的场景上。这能够保持大型套件的一致性并加快设置速度。
“环境”选择是人们最关心的设置。将夜间生产监控指向你的生产环境，并将发布前的冒烟测试指向预发环境。因为每个场景都可以指定自己的环境，如果需要的话，一个任务甚至可以混合不同的目标，尽管保持一个任务只对应单一环境会更容易理解。
4. 设置运行周期
将运行计划字段设置为你想要的频率。根据你所在的屏幕不同，此字段可能显示为“运行周期”或“运行模式”；它们是同一个设置，只是 UI 上的标签措辞有所不同。文档给出了一些你可以参考的具体示例：每周日晚上 11 点，每 6 小时，或者每 8 小时。
对于夜间回归测试，每天深夜运行一次既能保持较低的噪音，又能在工作日开始前发现问题。对于预发冒烟测试，每 6 小时运行一次可以在不给环境造成过大压力的情况下为你提供更快的反馈。
5. 选择运行位置
将 Runner 字段设置为你的自托管 Runner。与时间表字段类似，这个选项在不同屏幕上的标签也不一致，可能显示为 Runs on、Run On 等等；它们的意思都一样，即执行套件的机器。Apifox 云端也会显示在这里但即将推出，所以请选择自托管 Runner。如果你已经注册了几个通用 Runner，请挑选你需要的那一个，例如位于与你的 API 相同 VPC 内部的 Runner。
请记住，测试套件中发起的所有请求都是从这里指定的机器发送的，因此请选择一个网络视角与真实流量一致的 Runner。
6. 开启通知
启用“通知”，以便任务在出现问题时告诉你。文档推荐在定时任务中开启此项，这也是无人值守运行的核心意义：没有消息就是好消息，而失败必须尽快传达给你。
Apifox 原生支持以下渠道：Slack、Teams、Webhook、Jenkins 以及 Email。对于电子邮件，项目成员的地址会自动补全，你也可以手动输入非成员的地址，用于轮值班或共享收件箱。Slack 会将失败信息直接推送到你的团队频道中；而 Webhook 选项则允许你将其分发到任何其他运行的系统中，从 PagerDuty 到自定义接口。
你还可以选择告警触发的时机：每次运行后，或者仅在失败时。对于健康的夜间套件，“仅失败时”可以保持频道安静，直到真正需要关注时才发声。而在不稳定的发布期间，“每次运行”则能提供一种心跳检测，确认任务确实在执行。
7. 保存并启用
打开任务的开关以启用它，它便会按照你设定的频率开始运行。你可以稍后将其禁用而无需删除，这在计划内停机或嘈杂的迁移窗口期间非常有用。
8. 查看运行历史
每次运行后，结果会自动从 Runner 上传回服务端。在客户端中打开“定时任务 - 运行历史”部分即可查看。这是你的审计追踪记录：哪次运行通过了、哪次失败了、哪个断言报错了，以及发生的时间。当 Slack 中收到告警时，“运行历史”就是你查看背后细节的地方。
高级设置与变体
一旦基础任务跑通，一些选项可以让它更加稳健。
变量作用域。当你的场景在运行之间传递数据时，Apifox 提供了从小到大三个共享级别：“仅在当前测试场景中共享”，这会将变量保留在该单一场景的专用文件中；“在当前定时任务的所有测试场景中共享”，这允许同一个任务中的场景相互读取彼此的值；以及“在当前定时任务目录下的所有定时任务中共享”，这是最广的作用域。请挑选既能让数据流转又尽可能小的作用域，以免一个场景的认证 Token 泄露到不相关的场景中。
变量持久化。只有在测试场景设计页面上启用了“保留变量值”选项，值才会从一次运行传递到下一次运行。如果你的夜间运行需要昨天捕获的订单 ID 或刷新后的 Token，请开启此项。否则，每次运行都会从零开始，任何跨次运行的假设都会在不知不觉中被打破。
使用目录进行分组。随着套件的增长，在“定时任务”下创建目录，以便将生产监控与发布前检查分开。目录级别的变量作用域便可以让一组相关的任务清晰地共享前置设置。
订阅计划限制。你获得的定时运行次数取决于你的订阅计划。文档指出了 Apifox 定价页面上的具体数字，因此在设定激进的“每小时运行”频率之前请检查你的计划。如果你需要更深入地了解分组和更重度的排程模式，我们的高级定时任务演练指南提供了更多信息，而同系列的接口测试场景中的条件逻辑指南则帮助你优先构建值得安排定时执行的场景。对于初次建立无人值守检查的团队来说，这篇关于 CI 中夜间 API 测试运行的文章也非常匹配。
使用 Apifox CLI 实现工作流自动化
定时任务的 UI 是其中一条路径。Apifox CLI 则是另一种，并且非常实用：你可以在无头模式下运行保存的场景，然后让 cron 或你的 CI 提供商来处理调度频率。需要澄清的是，CLI 没有原生的调度命令；调度工作存在于 Apifox 之外，由你已经信任的 cron 工具来处理。
安装并完成鉴权后，根据 ID 针对所选环境运行场景。Apifox CLI 安装指南全面涵盖了 Token 的设置：
npm install -g apifox-cli
apifox login --with-token <YOUR_TOKEN>
apifox run --access-token $APIFOX_ACCESS_TOKEN -t <SCENARIO_ID> -e <ENV_ID> -r cli,junit
这里的 -t 是测试场景的 ID，-e 是环境 ID，而 -r 是测试报告的输出格式（cli、html 或 junit，如有多个可以用逗号分隔）。要通过 cron 让它在夜间运行，只需添加一行：
0 2 * * * cd /srv/api-tests && apifox run --access-token $APIFOX_ACCESS_TOKEN -t 4471 -e 88 -r junit >> run.log 2>&1
或者从定时执行的 GitHub Actions 任务中触发它。无论哪种方式，JUnit 报告都会直接进入你现有的流水线仪表盘。有关完整的设置，包括 cron 和 GitHub Actions 计划触发器，请参阅你 CI/CD 流水线中的 Apifox CLI。
常见问题解答
我目前可以在 Apifox 云端上运行定时测试吗？ 暂时还不行。Runner 目标列表中显示 Apifox 云端“即将推出”，因此目前自托管 Runner 是唯一可用的执行机器。请先注册一个 Runner，然后在任务中选择它。
定时任务可以多久运行一次？ 这取决于你订阅计划允许的频率。运行频率本身是很灵活的，正如文档中举例的“每 6 小时”或“每周日晚 11 点”，但定时运行的总次数是受你订阅限制的。请查看 Apifox 定价页面了解你所在层级的具体上限，而不是随意猜测。
我如何才能只在测试失败时收到通知？ 在任务的“通知”设置中，选择“仅失败时”选项而不是“每次运行”，然后添加一个渠道：Slack、Teams、Webhook、Jenkins 或 Email。这可以让你在一切正常时保持频道的清净，并在出错时大声发出警报。将其与轻量级的 API 健康检查结合使用，可作为深入回归套件之外的快速存活信号。
为什么我定时运行的结果与本地测试运行的不同？ 因为请求来自 Runner 的机器，而不是你的笔记本电脑。它的网络、地域以及任何 VPN 或防火墙都会影响响应结果。这是符合预期的，通常这也更能真实地反映你用户所访问到的情况。
我的变量每次运行都会重置，我漏掉了什么？ 在测试场景设计页面上的“保留变量值”选项。启用它，捕获到的值就能从一次运行保留到下一次。如果没有开启，每一次定时运行都会重新开始，所有的跨运行依赖都会失效。
总结
定时测试将“我们认为 API 可以工作”变成了“我们确信它在工作，否则我们早就收到警报了”。只需构建一次测试场景，注册一个自托管 Runner，设置好运行周期，绑定失败时的 Slack 或邮件通知，就可以放心地让它在你睡觉时自动运行。如果你想在流水线中进行同样的检查，CLI 加 cron 的组合为你提供了无需额外工具的另一种路径。下载 Apifox 以配置你的首个定时回归套件。起步完全免费，无需绑定信用卡。