已安装@fastify/swagger仍提示找不到模块或类型声明的问题

我是后端开发新手，正在使用Fastify、TypeScript、PostgreSQL、Prisma和Docker搭建简易后端服务，此前一切正常。添加Swagger API文档时遇到问题：

我的index.ts代码 #

import fastify from "fastify";
import inventoryRoutes from "./routes/inventoryRoutes";
import fastifySwagger from "@fastify/swagger";
import fastifySwaggerUi from "@fastify/swagger-ui";

const server = fastify();

const swaggerOptions = {
  swagger: {
      info: {
          title: "My Title",
          description: "My Description.",
          version: "1.0.0",
      },
      host: "localhost",
      schemes: ["http", "https"],
      consumes: ["application/json"],
      produces: ["application/json"],
      tags: [{ name: "Default", description: "Default" }],
  },
};

const swaggerUiOptions = {
  routePrefix: "/docs",
  exposeRoute: true,
};

server.register(fastifySwagger, swaggerOptions);
server.register(fastifySwaggerUi, swaggerUiOptions);

// Register routes
inventoryRoutes(server);

// Start server
server.listen({ port: 8080, host: "0.0.0.0" }, (err, address) => {
  if (err) {
    console.error(err);
    process.exit(1);
  }
  console.log(`Server listening at ${address}`);
});

运行docker compose up时的错误输出 #

inventory-api-1  | src/index.ts(3,28): error TS2307: Cannot find module '@fastify/swagger' or its corresponding type declarations.
inventory-api-1  | src/index.ts(4,30): error TS2307: Cannot find module '@fastify/swagger-ui' or its corresponding type declarations.

尽管我已安装这些依赖，package.json中也能看到它们，且IDE无报错，但容器运行时仍出现该问题，请问我哪里出错了？

解决方案 #

1. 检查Dockerfile的构建逻辑 #

容器内未安装依赖是最常见的原因，需确保Dockerfile包含完整的依赖安装步骤：

• 先复制package.json和package-lock.json（或yarn.lock）到容器，再执行安装命令，避免因源码变动导致依赖层缓存失效。
• 示例正确的Dockerfile片段：

# 依赖安装阶段
FROM node:18-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci  # 使用ci确保安装lock文件中指定的精确版本

# 构建TypeScript代码阶段
FROM node:18-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# 运行阶段
FROM node:18-alpine AS runner
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
EXPOSE 8080
CMD ["npm", "start"]

2. 清理Docker缓存 #

Docker可能缓存了旧的依赖层，导致新添加的@fastify/swagger和@fastify/swagger-ui未被安装。执行以下命令彻底清理后重新构建：

docker compose down --rmi all -v
docker compose build --no-cache
docker compose up

3. 验证容器内的依赖是否存在 #

进入运行中的容器，检查依赖是否安装成功：

docker exec -it inventory-api-1 sh
ls node_modules/@fastify/

如果输出中没有swagger和swagger-ui，说明依赖安装过程存在问题，需检查package.json中的依赖名称是否正确（确保是@fastify/swagger而非已废弃的fastify-swagger）。

4. 本地重新安装依赖后重建镜像 #

若本地依赖存在但容器内缺失，可先在本地重新安装依赖，再重新构建Docker镜像：

rm -rf node_modules package-lock.json
npm install
docker compose build --no-cache
docker compose up

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