任务
Nitro 任务允许在运行时进行开关操作。
Nitro v3 Alpha 文档仍在开发中 — 预计会有更新、不完善之处及偶尔的错误。
选择实验性功能
任务支持目前是实验性的。
请查看 nitrojs/nitro#1974 以获取相关讨论。
为了使用任务 API，您需要启用实验性功能标志。
import { defineNitroConfig } from "nitro/config";
export default defineNitroConfig({
experimental: {
tasks: true
}
})
export default defineNuxtConfig({
nitro: {
experimental: {
tasks: true
}
}
})
::
定义任务
任务可以在 server/tasks/[name].ts 文件中定义。
支持嵌套目录。任务名称将通过 : 连接。（例：server/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: "成功" };
},
});
定时任务
您可以使用 Nitro 配置定义定时任务，以便在每段时间后自动运行。
import { defineNitroConfig } from "nitro/config";
export default defineNitroConfig({
scheduledTasks: {
// 每分钟运行一次 `cms:update` 任务
'* * * * *': ['cms:update']
}
})
export default defineNuxtConfig({
nitro: {
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 };
},
});
// [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
}
}
包含在正文中的 JSON 负载将覆盖查询参数中存在的键。
使用 CLI
只能在 开发服务器运行 时运行这些命令。您应该在第二个终端中运行它们。
列出任务
nitro task list
运行任务
nitro task run db:migrate --payload "{}"
注意事项
并发
每个任务只能有 一个运行实例。在并行调用同一个名称的任务多次时，实际上只调用一次，所有调用者将获得相同的返回值。
Nitro 任务可以多次同时运行。
