Fastify注册路由报错AvvioError：Plugin did not start in time问题咨询

报错信息 #

AvvioError [Error]: Plugin did not start in time: 'declareHealthRoutes'. You may have forgotten to call 'done' function or to resolve a Promise

问题代码 #

routes.ts #

import { declareArticleRoutes } from "./articlesRoutes";
import { declareContactRoutes } from "./contactRoutes";
import { declareAdminRoutes } from "./adminRoutes";
import { verifyJWT} from "../services/tokenService";
import { declareHealthRoutes } from "./healthRoutes";
function declareRoutes(fastify: FastifyInstance) {
    fastify.register(declareArticleRoutes);
    fastify.register(declareContactRoutes);
    fastify.register(declareHealthRoutes);
    fastify.register(declareAdminRoutes);
}

healthRoutes.ts #

import {FastifyInstance, FastifyReply, FastifyRequest} from "fastify";

const healthSchema = {
    response: {
        200: {}
    }
};

function declareHealthRoutes(fastify: FastifyInstance): FastifyInstance {

    fastify.route({
        method: 'GET',
        url: '/health2',
        schema: healthSchema,
        handler: (req: FastifyRequest, reply: FastifyReply) => {
            return reply.status(200).send({});
        },
    });
    return fastify
}

export { declareHealthRoutes };

原因分析 #

Fastify的register方法要求传入的插件函数必须遵循Fastify插件规范：

• 要么接受第二个done回调参数，在路由注册完成后调用done()告知Fastify插件初始化结束
• 要么返回一个Promise（可通过async函数实现）

你的declareHealthRoutes只是返回Fastify实例，没有触发Fastify插件加载机制的完成信号，导致Fastify判定插件未启动完成，超时抛出错误。

而直接调用declareHealthRoutes(fastify)能生效，是因为这种方式跳过了Fastify的插件加载流程，只是在当前上下文直接执行路由注册，不需要遵循插件的回调/Promise规范。

解决方法 #

方法1：使用done回调（同步场景推荐） #

修改healthRoutes.ts中的函数，添加done参数并调用：

import {FastifyInstance, FastifyReply, FastifyRequest} from "fastify";

const healthSchema = {
    response: {
        200: {}
    }
};

function declareHealthRoutes(fastify: FastifyInstance, done: () => void) {
    fastify.route({
        method: 'GET',
        url: '/health2',
        schema: healthSchema,
        handler: (req: FastifyRequest, reply: FastifyReply) => {
            return reply.status(200).send({});
        },
    });
    done(); // 告知Fastify插件初始化完成
}

export { declareHealthRoutes };

方法2：返回Promise（异步场景推荐） #

将函数改为async函数，自动返回Promise：

import {FastifyInstance, FastifyReply, FastifyRequest} from "fastify";

const healthSchema = {
    response: {
        200: {}
    }
};

async function declareHealthRoutes(fastify: FastifyInstance) {
    fastify.route({
        method: 'GET',
        url: '/health2',
        schema: healthSchema,
        handler: (req: FastifyRequest, reply: FastifyReply) => {
            return reply.status(200).send({});
        },
    });
}

export { declareHealthRoutes };

所有路由文件都需要按上述两种方式之一修改，才能通过fastify.register正常加载。

内容的提问来源于stack exchange，提问作者Symtox