测试套件只有持续通过才有意义。您的结账流程今天运行正常，但某个依赖项可能会在凌晨 2 点发布破坏性变更，证书可能会在周末过期，或者配置漂移可能会在周日导致支付接口挂掉。您往往是从愤怒的客户那里得知这些问题，而不是通过测试运行。解决方案简单且可靠：按计划定时运行 API 测试，无需人工点击按钮，并在出现问题时第一时间收到通知。
Apifox 内置的定时任务功能正是为此而设计的。您可以将其指向已构建的测试场景，设置执行周期，选择运行的机器，并配置告警。本指南将如实介绍所有相关内容，包括当前的限制。如果您是第一次对生产接口进行无人值守的检查，我们关于 API 监控的入门文章将为您提供更广泛的背景信息，而 Apifox 定时任务文档则是了解其界面的权威来源。
在开始之前，请注意一点。定时任务功能目前带有 Beta 标签，且您的账户拥有的定时运行次数取决于您的订阅计划。阅读时请记住这两点。
AI Coding 交流群
如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。
定时任务的作用（以及它们与定时爬虫的区别）
Apifox 中的定时任务可以按周期循环运行一个或多个已保存的测试场景。例如，对核心 API 进行每晚回归测试、每隔几小时对预发环境进行一次冒烟测试，或者在周末进行健康检查。该任务会记住要运行哪些场景、请求哪个环境、触发频率如何、由哪台机器执行工作，以及在失败时通知谁。
如果您曾见过将“定时任务”这一词汇与网页抓取（Web Scraping）或数据收集联系在一起，那属于另外一回事。此功能并不是为了定时爬取页面，它存在于测试模块中，用于驱动您的 API 测试场景：包括断言、链式请求、提取的变量等一系列操作。其输出是关于 API 契约的通过或失败报告，而不是抓取的数据集。
这种区别非常重要，因为它改变了您需要配置的内容。您不需要编写选择器或爬取规则，而是选择现有的测试场景，并告诉 Apifox 何时以及在何处运行它们。
开始之前：配置自托管 Runner
这是最容易让人卡住的前提条件。要运行定时任务，您首先需要配置一个自托管的 Runner。文档对此有明确说明。
Runner 是执行测试套件的机器。当定时任务触发时，Apifox 不会在您的桌面版客户端中运行请求；它会将任务交给您选择的 Runner，测试套件中的每个请求都从该机器发送。CI 机器、小型常开服务器或专用虚拟机都可以很好地胜任。无论您选择什么，它都需要在您设定的日程内保持唤醒且可访问。
runner 目标字段提供了两个选项：标记为“即将推出”的 Apifox Cloud，以及自托管 Runner。由于 Apifox Cloud 目前尚不可用，自托管 Runner 是现阶段唯一可用的选项。在云端执行功能正式发布前，请先不要基于它进行规划。
由于请求源自 Runner 所在的机器，其网络环境会直接影响运行结果。处于企业 VPN、不同地区或受防火墙保护的子网中的 Runner，其接收到的响应可能与你的笔记本电脑有所不同。对于真实监控而言，这通常正是你所期望的，但当定时运行的结果与本地运行不一致时，了解这一点有助于排查问题。
逐步指南：创建定时任务
注册 Runner 后，其余操作都可以在客户端中完成。下面我们以一个电商 API 的每晚回归测试套件为例，该套件涵盖了用户注册、商品列表、购物车以及由 Stripe 支持的结账流程。
1. 打开测试模块中的定时任务
在 Apifox 客户端中打开“测试”模块。在测试目录树中，点击“定时任务”以查看和管理项目中的每一个定时任务。整个项目中的所有任务都会显示在“定时任务”列表下，你可以在这里统一查看哪些任务正在运行以及运行时间。
2. 创建任务
点击“+ 新建”以创建新的定时任务。你也可以在此处创建目录来对相关任务进行分类，这在需要针对预发布（staging）和生产（production）环境或不同服务区分测试套件时非常有用。
为任务设置清晰的“任务名称”和“描述”。这些内容有助于区分不同的任务并说明其用途，方便你以后无需打开任务就能明白“Nightly regression, prod”具体包含什么。每个任务都有一个启用/禁用开关，目录树中的任务可以随时启用或禁用。
3. 选择要运行的测试场景
在“测试场景”下方，选择要包含的一个或多个场景。在前面的电商示例中，你可以选择“注册并登录”、“浏览并添加到购物车”以及“使用 Stripe 测试卡结账”，从而用单个任务覆盖整个核心业务路径。
每个场景都可以拥有独立的执行设置，包括：环境、测试数据、循环次数、延迟，以及是否保存请求和响应。如果你不想逐一调整，可以开启“使用相同运行配置”，从而一键将统一的运行时配置应用到所有选定的场景中。这有助于保持大型测试套件的一致性，并提高配置效率。
环境选择是用户最关心的设置。你可以将每晚的生产监控指向 prod 环境，而将发布前的冒烟测试指向 staging 环境。由于每个场景都可以指定自己的环境，如果需要，单个任务甚至可以混用不同的目标环境，不过将单个任务限制在单一环境中会让逻辑更加清晰。
4. 设置运行周期
将 run-schedule 字段设置为你所需的执行频率。根据你所处的界面，该字段可能显示为 Run Cycle 或 Run Mode；它们是同一个设置，只是在不同 UI 界面中的标签文案有所不同。文档中提供了一些可以参考的具体示例：每周日晚上 11 点、每 6 小时或每 8 小时。
对于夜间回归测试，每日深夜运行可以减少干扰，并在工作日开始前捕获问题。对于 staging 环境的冒烟测试，每 6 小时运行一次可以提供更快的反馈，而不会给环境带来过大压力。
5. 选择运行位置
将 runner 字段设置为你的自托管 Runner。与 schedule 字段类似，该字段在不同界面中的标签可能不一致，如 Runs on、Run On 或 Runs On；它们代表同一个意思，即执行测试套件的机器。Apifox Cloud（云端）也会出现在这里，但该功能即将推出，因此请选择你的自托管 Runner。如果你注册了多个通用 runner，请选择你需要的特定 Runner，例如与你的 API 处于同一 VPC 内的 Runner。
请记住，测试套件中发起的所有请求（request）都将从此处指定的机器发送，因此请选择一个网络环境能够像真实流量一样访问你的 API 的 Runner。
6. 开启通知
启用 Notification（通知），以便在出现问题时定时任务（scheduled task）能够通知你。文档建议为定时任务开启此功能，这也是无人值守运行的核心意义所在：静默代表成功，而失败则应快速送达。
Apifox 支持以下通道：Slack、Teams、Webhook、Jenkins 和 Email。对于 Email，项目（project）成员（member）的邮箱地址会自动补全，你也可以手动输入非成员的地址，以便用于值班轮换或共享收件箱。Slack 会将失败直接推送到你的团队频道；Webhook 选项则允许你将通知分发到你运行的任何其他服务，从 PagerDuty 到自定义接口（endpoint）。
你还可以选择何时触发告警：每次运行后，或仅在失败时。对于状态良好的夜间测试套件，“仅失败时”可以保持频道安静，直到出现关键问题。在不稳定的版本发布期间，“每次运行”可以提供心跳检测，以确认任务确实在执行。
7. 保存并启用
开启该任务的开关以启用它，它就会开始按照你设置的频率运行。你稍后可以禁用它而无需删除，这在计划内停机或嘈杂的迁移窗口期间非常有用。
8. 查看运行历史
每次运行后，结果会自动从 Runner 上传回服务端（server）。在客户端中打开“定时任务 - 运行历史”部分即可查看它们。这是你的审计追踪：哪次运行通过了、哪次失败了、哪个断言报错了以及具体的时间。当 Slack 中收到告警时，你可以通过“运行历史”来查看其背后的详细信息。
高级设置与变体
基本任务运行起来后，有一些选项可以让它更加健壮。
变量作用域。当你的测试场景在多次运行之间传递数据时，Apifox 提供了三个共享层级，从窄到宽依次为：仅在当前测试场景中共享（将变量保存在该测试场景的专属文件中）；在当前定时任务的所有测试场景中共享（允许同一任务中的测试场景互相读取数值）；以及在当前定时任务目录下的所有定时任务中共享（范围最广）。建议选择能满足数据流转的最小作用域，这样可以避免某个测试场景的 auth Token 泄露到其他无关的测试场景中。
变量持久化。只有在测试场景设计页面启用“保存变量值”选项时，变量值才会在多次运行之间传递。如果你的每日夜间运行需要用到昨天捕获的订单 ID 或刷新后的 Token，请开启此选项。如果不启用，每次运行都会以干净的状态开始，任何跨运行的数据假设都可能会悄无声息地失效。
使用目录进行分组。随着测试套件的增长，你可以在“定时任务”下创建目录，以区分（例如）生产环境监控和发布前检查。目录级的变量作用域可以让一组相关的任务干净地共享配置。
套餐限制。你可以使用的定时运行次数取决于你的订阅版本。文档中提供了指向 Apifox 定价页面的链接以获取确切的数据，因此在设置激进的每小时运行频率之前，请先检查你的套餐额度。如果你需要更深入地了解分组和更复杂的定时模式，我们关于高级定时任务的详细指南会提供更多帮助，而关于 API 测试场景中条件逻辑的配套指南则能帮助你构建真正值得定时运行的测试场景。对于首次搭建无人值守检查的团队来说，关于在 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 $APIFOXACCESSTOKEN -t 4471 -e 88 -r junit >> run.log 2>&1
或者通过定时 GitHub Actions 工作流进行触发。无论采用哪种方式，JUnit 报告都会自动呈现在您现有的流水线仪表盘中。有关完整设置（包括 cron 和 GitHub Actions 定时触发器），请参阅在 CI/CD 流水线中使用 Apifox CLI。
FAQ
我目前可以在 Apifox 云端运行定时测试吗？ 暂时还不支持。运行器目标（runner target）中将 Apifox 云端列为“即将推出”，因此目前自托管 Runner 是唯一可用的执行机器。请先注册一个 Runner，然后在任务中选择它。
定时任务可以运行得有多频繁？ 频率取决于您套餐的允许范围。执行周期本身非常灵活，文档中给出的示例包括每 6 小时运行一次或每周日晚上 11 点运行一次，但定时运行的次数受您订阅计划的限制。请查看 Apifox 价格页面以了解您所在层级的确切限制，而不是自己估算一个数字。
如何设置仅在测试失败时接收通知？ 在任务的“通知”设置中，选择“仅失败时”选项（而非每次运行都通知），然后添加通道：Slack、Teams、Webhook、Jenkins 或电子邮件。这样可以确保在一切正常时保持安静，而在出现问题时能及时发出警报。您还可以将其与轻量级的 API 健康检查结合使用，在进行更深维度的回归测试套件运行之余，提供快速的存活信号（liveness signal）。
为什么我的定时任务运行结果与本地测试运行结果不同？ 因为请求发送自运行 Runner 的机器，而非您的个人电脑。其网络、地域以及任何 VPN 或防火墙设置都会影响响应结果。这是正常现象，并且通常更能真实反映用户所面临的实际网络状况。
我的变量在每次运行时都会重置，我漏掉了什么？ 漏掉了测试场景设计页面上的“保持变量值”选项。启用它后，捕获的变量值将从一次运行传递到下一次运行。如果不启用，每次定时运行都会从头开始，任何跨运行的依赖关系都将失效。
总结
定时测试将“我们认为 API 正常工作”转变为“我们确信它在正常工作，因为如果不正常，我们早就收到告警了”。只需构建一次测试场景，注册一个自托管 Runner，设置好运行周期，配置好失败时发送 Slack 或电子邮件通知，即可让它在您入睡时自动运行。当您需要在流水线中进行相同的检查时，CLI 结合 cron 为您提供了无需任何额外工具的第三种途径。下载 Apifox 来构建您的首个定时回归测试套件。免费开始，无需信用卡。
开发必备：API 全流程管理神器 Apifox
介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、调试、设计、测试、Mock、自动化测试于一体的工具，Apifox 是目前提升研发效率的首选。
如果你正在开发项目，不妨试试其极其友好的界面设计，它完全兼容 Postman 和 Swagger 数据格式，导入数据非常方便，，即使是新手也能很快上手，点击这里即可注册使用。
值得一提的是，除了个人和常规团队使用，针对有高安全合规要求、或需要在内网环境协作的企业，Apifox 还提供了深度定制的私有化部署方案。
获取专属报价与部署方案
详细的私有化部署系统架构与安全白皮书
针对您公司规模的专属报价单
免费的 1v1 专属产品演示 (Demo) 机会
