将Fastify自定义authenticate装饰器移至独立声明文件时遇TS错误

问题描述 #

使用TypeScript开发Fastify应用，基于@fastify/jwt和@fastify/cookie实现认证逻辑，自定义了authenticate装饰器用于路由前置校验。直接在server.ts内定义类型声明时一切正常，但将类型声明迁移到项目根目录的fastify.d.ts并通过tsconfig.json引入后，TypeScript抛出错误：

{
  "resource": "/u:/dekada/api/src/models/teacher/teacher.route.ts",
  "owner": "typescript",
  "code": "2339",
  "severity": 8,
  "message": "Property 'authenticate' does not exist on type 'FastifyInstance<RawServerDefault, IncomingMessage, ServerResponse<IncomingMessage>, FastifyBaseLogger, FastifyTypeProviderDefault>'.",
  "source": "ts",
  "startLineNumber": 32,
  "startColumn": 41,
  "endLineNumber": 32,
  "endColumn": 53
}

当前fastify.d.ts内容：

import { FastifyInstance } from "fastify";

declare module "fastify" {
  export interface FastifyInstance {
    authenticate: any; // Replace 'any' with a more specific type if possible
  }
}

tsconfig.json的include配置：

{
  "include": [
    "src/**/*",
    "fastify.d.ts"
  ],
  "exclude": ["node_modules"]
}

解决方案 #

1. 修正fastify.d.ts的模块扩展声明 #

扩展Fastify模块时，不要在模块外部导入FastifyInstance，而是在模块内部按需导入类型，同时替换any为具体的函数类型以保证类型安全：

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

这种写法可以避免因外部导入导致的模块隔离问题，确保TypeScript正确识别扩展的接口。

2. 移除server.ts中的重复类型声明 #

之前server.ts内存在重复的declare module "fastify"代码块，会与fastify.d.ts的声明冲突，必须删除这段代码：

// 删掉这段重复声明
declare module "fastify" {
  export interface FastifyInstance {
    authenticate: any;
  }
}

3. 确保TypeScript正确识别类型文件 #

• 确认tsconfig.json的include已经包含fastify.d.ts（当前配置已满足）
• 若仍有问题，可在compilerOptions中添加typeRoots确保TypeScript扫描当前目录的类型文件：

"compilerOptions": {
  "typeRoots": ["./", "node_modules/@types"]
}

4. 重启TypeScript服务 #

修改类型声明后，重启TypeScript语言服务（VSCode中可通过Ctrl+Shift+P -> TypeScript: Restart TS Server），确保新的类型声明被加载。

问题原因 #

在server.ts内直接声明类型时，路由文件通过导入server实例间接获取了扩展类型；但迁移到单独的fastify.d.ts后，错误的导入方式导致模块扩展未被TypeScript正确识别，加上重复的类型声明引发冲突，最终导致路由文件无法识别authenticate属性。

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