Fastify+TypeScript报错：FastifyInstance不存在authenticate属性

问题描述 #

在Fastify+TypeScript项目中使用authenticate方法时，TypeScript抛出如下错误：

Property 'authenticate' does not exist on type 'FastifyInstance<RawServerDefault, IncomingMessage, ServerResponse<IncomingMessage>, FastifyBaseLogger, FastifyTypeProviderDefault>'.

引发问题的路由代码：

import { FastifyInstance, FastifyPluginOptions } from "fastify";
import { UserController } from "../controllers/UserController";

const userRoutes = async (
  fastify: FastifyInstance,
  options: FastifyPluginOptions
) => {
  fastify.addHook("preHandler", fastify.authenticate);

  fastify.get("/", UserController.getUsers);
  fastify.get("/:id", UserController.getUserById);
  fastify.get("/mail/:mail", UserController.getUserByMail);
  fastify.get("/user/:user", UserController.getUserByUser);
};

export default userRoutes;

已尝试的解决方案 #

1. 在主文件中为Fastify实例装饰authenticate方法：

import fastify, { FastifyReply, FastifyRequest } from "fastify";
import { connectDB } from "./config/db";
import userRoutes from "./routes/userRoutes";
import projectsRoutes from "./routes/projectRoutes";
import fastifyJwt from "@fastify/jwt";

const app = fastify({ logger: true });

app.register(fastifyJwt, {
  secret: process.env.SECRET_KEY || "secret_key",
});

app.decorate("authenticate", async function (request, reply) {
  try {
    await request.jwtVerify();
  } catch (err) {
    reply.send(err);
  }
});

app.register(userRoutes, { prefix: "/api/v1/user" });
app.register(projectsRoutes, { prefix: "/api/v1/project" });

connectDB();
export default app;

2. 创建src/types/fastify.d.ts类型定义文件：

import "fastify";

declare module "fastify" {
  export interface FastifyInstance {
    authenticate: any;
  }
}

3. tsconfig.json配置：

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./src/types"],
    "outDir": "./dist",
    "rootDir": "./src",
    "lib": ["esnext"],
    "target": "ESNext",
    "moduleResolution": "NodeNext",
    "module": "NodeNext",
    "strict": false,
    "sourceMap": true,
    "esModuleInterop": true,
    "declaration": true
  },
  "include": ["src/**/*.ts"]
}

完整错误输出 #

/home/user/project/node_modules/ts-node/src/index.ts:859
    return new TSError(diagnosticText, diagnosticCodes, diagnostics);
           ^
TSError: ⨯ Unable to compile TypeScript:
src/routes/userRoutes.ts:8:41 - error TS2339: Property 'authenticate' does not exist on type 'FastifyInstance<...>'.

8   fastify.addHook("preHandler", fastify.authenticate);
                                          ~~~~~~~~~~~~

解决方法 #

1. 完善类型定义，避免使用any #

把src/types/fastify.d.ts里的authenticate类型从any改成明确的函数类型，让TypeScript能准确识别：

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

declare module "fastify" {
  export interface FastifyInstance {
    authenticate: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
  }
}

2. 确保类型文件被正确扫描 #

检查tsconfig.json的include字段，显式添加.d.ts类型文件的匹配规则，避免遗漏：

"include": ["src/**/*.ts", "src/**/*.d.ts"]

3. 清除TypeScript缓存 #

编辑器的TypeScript服务可能缓存了旧的类型信息，重启编辑器或者手动重启TS服务（比如VSCode中按Ctrl+Shift+P选择「TypeScript: Restart TS Server」），强制刷新类型检测。

4. 验证装饰器注册顺序 #

确认主文件中先调用app.decorate注册authenticate，再注册路由插件——你的当前代码顺序是正确的，这一步主要排查是否存在异步注册导致的顺序问题。

内容的提问来源于stack exchange，提问作者luis angel camargo guzman