如何在NestJS中用Fastify提供静态文件？解决路由冲突等报错

问题1：main.ts注册@fastify/static自定义路由报错 #

直接调用Fastify实例的register方法注册静态插件时，Nest的路由解析逻辑无法识别该路由，导致报错。正确做法是通过Nest的app.register方法注册，并注意前缀格式：

步骤： #

1. 安装依赖：

npm install @fastify/static

2. 修改main.ts：

import { NestFactory } from '@nestjs/core';
import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';
import { AppModule } from './app.module';
import fastifyStatic from '@fastify/static';
import { join } from 'path';

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter(),
  );

  // 注册静态文件插件，prefix末尾需加斜杠
  await app.register(fastifyStatic, {
    root: join(__dirname, '..', 'client'), // 静态文件根目录
    prefix: '/another/path/', // 访问前缀
  });

  await app.listen(3000);
}
bootstrap();

注意： #

• 确保/another/path/前缀未被Nest控制器占用，避免路由冲突
• 静态文件目录client需存在，且index.html在该目录下

问题2：ServeStaticModule报HEAD方法重复声明 #

错误原因为ServeStaticModule默认会为目标路由注册GET和HEAD方法，与现有路由或Fastify配置冲突。解决方法是禁用HEAD方法或调整路由前缀：

步骤： #

1. 安装依赖：

npm install @nestjs/serve-static

2. 修改app.module.ts：

import { Module } from '@nestjs/common';
import { ServeStaticModule } from '@nestjs/serve-static';
import { join } from 'path';
import { AppController } from './app.controller';
import { AppService } from './app.service';

@Module({
  imports: [
    ServeStaticModule.forRoot({
      rootPath: join(__dirname, '..', 'client'),
      serveRoot: '/another/path', // 访问前缀
      serveStaticOptions: {
        methods: ['GET'], // 仅启用GET方法，避免HEAD重复声明
      },
    }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

额外排查： #

• 检查是否有控制器或其他插件注册了/或/another/path的HEAD请求
• 避免同时使用@fastify/static和ServeStaticModule处理同一前缀

依赖版本匹配建议 #

确保以下依赖版本适配：

• @nestjs/platform-fastify: 9.0.0
• @fastify/static: 6.x（适配Fastify 4.x，NestJS 9默认依赖）
• @nestjs/serve-static: 3.x

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