选择加入实验功能
请参阅 unjs/nitro#1974 了解相关讨论。
为了执行任务 API，您需要启用实验性功能标志。
ts
nitro.config.ts
ts
export default defineNitroConfig({
experimental: {
tasks: true
}
})
定义任务
任务可以在 tasks/[name].ts 文件中定义。
支持嵌套目录。任务名称将以 : 连接。（例如：tasks/db/migrate.ts 任务名称将是 db:migrate）
例如:
tasks/db/migrate.ts
ts
export default defineTask({
meta: {
name: 'db:migrate',
description: 'Run database migrations',
},
run({ payload, context }) {
console.log('Running DB migration task...')
return { result: 'Success' }
},
})
Use server/tasks/db/migrate.ts for Nuxt.
计划任务
您可以使用 Nitro 配置定义计划任务，使其在每个时间段后自动运行。
ts
nitro.config.ts
ts
export default defineNitroConfig({
scheduledTasks: {
// 每分钟运行一次 `cms:update` 任务
'* * * * *': ['cms:update']
}
})
您可以使用 crontab.guru 轻松生成和理解 cron tab 模式。
Platform support
dev、node-server、bun和deno-server预设均受 croner 引擎支持。cloudflare_module预设与 Cron Triggers 原生集成。 确保将 wrangler 配置为使用与scheduledTasks中定义的完全相同的模式进行匹配。- 计划支持更多预设（具有原生原语支持）！
以编程方式运行任务
要手动运行任务，您可以使用runTask（name，{payload？}）实用程序。
例如:
ts
// 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
此端点返回可用任务名称及其元数据的列表。
json
// [GET] /_nitro/tasks
{
"tasks": {
"db:migrate": {
"description": "Run database migrations"
},
"cms:update": {
"description": "Update CMS content"
}
},
"scheduledTasks": [
{
"cron": "* * * * *",
"tasks": [
"cms:update"
]
}
]
}
/_nitro/tasks/:name
此端点执行一项任务。您可以使用查询参数和主体 JSON 负载提供负载。JSON 主体负载中发送的负载必须位于payload属性下。
ts
tasks/echo/payload.ts
ts
export default defineTask({
meta: {
name: 'echo:payload',
description: 'Returns the provided payload',
},
run({ payload, context }) {
console.log('Running echo task...')
return { result: payload }
},
})
主体中包含的 JSON 有效负载将覆盖查询参数中存在的键。
Using CLI
只有在开发服务器正在运行时才可以运行这些命令。您应该在第二个终端中运行它们。
List tasks
sh
nitro task list
Run a task
sh
nitro task run db:migrate --payload "{}"
Notes
Concurrency
每个任务可以有一个运行实例。并行多次调用同名任务，结果只会调用一次，并且所有调用者都会获得相同的返回值。
Nitro 任务可以多次并行运行。