任务
Nitro 任务允许在 runtime 中进行一次性操作。
Nitro v3 Alpha 文档仍在开发中——可能会有更新、不完善的地方和偶尔的不准确信息。
选择加入实验性功能
任务支持目前是实验性的。
有关相关讨论，请参阅 nitrojs/nitro#1974。
为了使用任务 API，你需要启用实验性功能标志。
nitro.config.ts
import { defineNitroConfig } from "nitro/config";
export default defineNitroConfig({
experimental: {
tasks: true
}
})
定义任务
任务可以在 tasks/[name].ts 文件中定义。
支持嵌套目录。任务名称将用 : 连接。（例如：tasks/db/migrate.ts 任务名称将是 db:migrate）
示例：
tasks/db/migrate.ts
export default defineTask({
meta: {
name: "db:migrate",
description: "运行数据库迁移",
},
run({ payload, context }) {
console.log("运行数据库迁移任务...");
return { result: "Success" };
},
});
定时任务
你可以使用 Nitro 配置定义定时任务，以在每个时间段后自动运行。
nitro.config.ts
import { defineNitroConfig } from "nitro/config";
export default defineNitroConfig({
scheduledTasks: {
// 每分钟运行 `cms:update` 任务
'* * * * *': ['cms:update']
}
})
你可以使用 crontab.guru 轻松生成和理解 cron 表模式。
平台支持
dev、node-server、bun和deno-serverpreset 支持 croner 引擎。cloudflare_modulepreset 与 Cron Triggers 原生集成。确保配置 wrangler 使用与你在scheduledTasks中定义的完全相同的模式以匹配。- 计划支持更多具有原生原语支持的 preset！
程序化运行任务
要手动运行任务，你可以使用 runTask(name, { payload? }) 实用程序。
示例：
api/migrate.ts
export default eventHandler(async (event) => {
// 重要：验证用户身份并验证 payload！
const payload = { ...getQuery(event) };
const { result } = await runTask("db:migrate", { payload });
return { result };
});
使用开发服务器运行任务
Nitro 内置的 dev server 暴露任务以便轻松执行，无需程序化使用。
使用 API 路由
/_nitro/tasks
此端点返回可用任务名称及其元数据的列表。
// [GET] /_nitro/tasks
{
"tasks": {
"db:migrate": {
"description": "运行数据库迁移"
},
"cms:update": {
"description": "更新 CMS 内容"
}
},
"scheduledTasks": [
{
"cron": "* * * * *",
"tasks": [
"cms:update"
]
}
]
}
/_nitro/tasks/:name
此端点执行任务。你可以使用查询参数和 body JSON payload 提供 payload。在 JSON body payload 中发送的 payload 必须在 "payload" 属性下。
export default defineTask({
meta: {
name: "echo:payload",
description: "返回提供的 payload",
},
run({ payload, context }) {
console.log("运行 echo 任务...");
return { result: payload };
},
});
// [GET] /_nitro/tasks/echo:payload?field=value&array=1&array=2
{
"field": "value",
"array": ["1", "2"]
}
/**
* [POST] /_nitro/tasks/echo:payload?field=value
* body: {
* "payload": {
* "answer": 42,
* "nested": {
* "value": true
* }
* }
* }
*/
{
"field": "value",
"answer": 42,
"nested": {
"value": true
}
}
body 中包含的 JSON payload 将覆盖查询参数中存在的键。
使用 CLI
只能在开发服务器运行时运行这些命令。你应在第二个终端中运行它们。
列出任务
nitro task list
运行任务
nitro task run db:migrate --payload "{}"
注意事项
并发性
每个任务可以有一个运行实例。并行多次调用同名的任务，结果只会调用一次，所有调用者将获得相同的返回值。
Nitro 任务可以多次并行运行。