Guide
任务
Nitro 任务允许在运行时进行开关操作。
选择实验性功能
任务支持目前处于实验阶段。
查看 unjs/nitro#1974 获取相关讨论。
为了使用任务 API，您需要启用实验性功能标志。
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: "成功" };
},
});
对于 Nuxt，请使用
server/tasks/db/migrate.ts。定时任务
您可以使用 Nitro 配置定义定时任务，使其在每个时间间隔后自动运行。
export default defineNitroConfig({
scheduledTasks: {
// 每分钟运行一次 `cms:update` 任务
'* * * * *': ['cms:update']
}
})
您可以使用 crontab.guru 来轻松生成和理解 cron 表达式模式。
平台支持
dev、node-server、bun和deno-server预设支持 croner 引擎。cloudflare_module预设与 Cron Triggers 有本地集成。确保配置 wrangler 使用与您在scheduledTasks中定义的完全相同的模式以便匹配。- 计划支持更多的预设（带有本地原语支持）！
以编程方式运行任务
要手动运行任务，您可以使用 runTask(name, { payload? }) 工具。
示例：
// api/migrate.ts
export default eventHandler(async (event) => {
// 重要：验证用户和有效负载！
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("运行回声任务...");
return { result: payload };
},
});
包含在主体中的 JSON 有效负载将覆盖查询参数中存在的键。
使用 CLI
只能在 开发服务器运行时 运行这些命令。您应该在第二个终端中运行它们。
列出任务
nitro task list
运行任务
nitro task run db:migrate --payload "{}"
注意事项
并发
每个任务只能有 一个正在运行的实例。多次并行调用同一名称的任务，将导致只调用一次，所有调用者将获得相同的返回值。
Nitro 任务可以多次并行运行。