Lzh on GitHub

任务

Nitro 任务允许在运行时执行一次性操作。

启用实验性功能

任务支持目前处于实验阶段。 请参阅 nitrojs/nitro#1974 了解相关讨论。

要使用任务 API，您需要启用实验性功能标志。

export default defineNitroConfig({
  experimental: {
    tasks: true
  }
})

定义任务

任务可以在 server/tasks/[name].ts 文件中定义。

支持嵌套目录。任务名称将与 : 连接。（例如：server/tasks/db/migrate.ts 任务名称将是 db:migrate）

示例：

server/tasks/db/migrate.ts
export default defineTask({
  meta: {
    name: "db:migrate",
    description: "运行数据库迁移",
  },
  run({ payload, context }) {
    console.log("正在运行数据库迁移任务...");
    return { result: "成功" };
  },
});

计划任务

您可以使用 Nitro 配置定义计划任务，以便每隔一段时间自动运行。

export default defineNitroConfig({
  scheduledTasks: {
    // 每分钟运行 `cms:update` 任务
    '* * * * *': ['cms:update']
  }
})
您可以使用 crontab.guru 轻松生成和理解 cron tab 模式。

平台支持

  • dev、node-server、bun 和 deno-server 预设支持 croner 引擎。
  • cloudflare_module 预设与 Cron Triggers 原生集成。请确保配置 wrangler 以使用与您在 scheduledTasks 中定义的完全相同的模式进行匹配。
  • 计划支持更多预设（具有原生原语支持）！

以编程方式运行任务

要手动运行任务，您可以使用 runTask(name, { payload? }) 工具。

示例：

server/api/migrate.ts
export default eventHandler(async (event) => {
  // 重要：验证用户并验证 payload！
  const payload = { ...getQuery(event) };
  const { result } = await runTask("db:migrate", { payload });

  return { result };
});

使用开发服务器运行任务

Nitro 的内置开发服务器公开任务，以便轻松执行，无需编程使用。

使用 API 路由

/_nitro/tasks

此端点返回可用任务名称及其元数据列表。

// [GET] /_nitro/tasks
{
  "tasks": {
    "db:migrate": {
      "description": "运行数据库迁移"
    },
     "cms:update": {
      "description": "更新 CMS 内容"
    }
  },
  "scheduledTasks": [
    {
      "cron": "* * * * *",
      "tasks": [
        "cms:update"
      ]
    }
  ]
}

/_nitro/tasks/:name

此端点执行任务。您可以使用查询参数和 JSON 请求体负载提供有效负载。JSON 请求体负载中发送的有效负载必须位于 "payload" 属性下。

export default defineTask({
  meta: {
    name: "echo:payload",
    description: "返回提供的有效负载",
  },
  run({ payload, context }) {
    console.log("正在运行 echo 任务...");
    return { result: payload };
  },
});
JSON 请求体中包含的有效负载将覆盖查询参数中存在的键。

使用 CLI

仅在 开发服务器运行时 才能运行这些命令。您应该在第二个终端中运行它们。

列出任务

nitro task list

运行任务

nitro task run db:migrate --payload "{}"

注意事项

并发

每个任务可以有 一个运行实例。并行多次调用同名任务将导致只调用一次，并且所有调用者都将获得相同的返回值。

Nitro 任务可以多次并行运行。