升级Fastify至v4.2.1遇fastify-static版本不兼容错误，求解决

云原生阿岚

2026-8-25

问题描述

将Fastify从v3.29.0升级到v4.2.1后，启动项目时出现以下版本不匹配错误：

FastifyError [Error]: fastify-plugin: fastify-static - expected '3.x' fastify version, '4.2.1' is installed
     at Object.checkVersion (/var/www/node_modules/fastify/lib/pluginUtils.js:118:11)
     at Object.registerPlugin (/var/www/node_modules/fastify/lib/pluginUtils.js:133:16)
     at Boot.override (/var/www/node_modules/fastify/lib/pluginOverride.js:28:57)
     at Plugin.exec (/var/www/node_modules/avvio/plugin.js:79:33)
     at Boot.loadPlugin (/var/www/node_modules/avvio/plugin.js:272:10)
     at processTicksAndRejections (node:internal/process/task_queues:83:21) {
   code: 'FST_ERR_PLUGIN_VERSION_MISMATCH',
   statusCode: 500
 }

尝试安装@fastify/static@6.4.0后问题仍未解决，原Fastify v3版本的项目依赖如下：

"dependencies": {
    "@fastify/swagger": "^6.1.0",
    "axios": "^0.27.2",
    "deepmerge": "^4.2.2",
    "dotenv": "^16.0.0",
    "express": "^4.18.1",
    "fastify": "^3.29.0",
    "fastify-decorators": "3.12.0",
    "http-status-codes": "2.2.0",
    "jwt-decode": "3.1.2",
    "node-mocks-http": "^1.11.0",
    "nodemon": "^2.0.16",
    "qs": "^6.10.3",
    "ts-node": "^10.7.0",
    "winston": "^3.7.2",
    "winston-daily-rotate-file": "^4.7.1"
  },
  "devDependencies": {
    "@fastify/redis": "^5.0.0",
    "@tsconfig/node16-strictest-esm": "^1.0.2",
    "@types/jest": "^27.5.2",
    "@types/node": "^17.0.27",
    "@types/qs": "^6.9.7",
    "@typescript-eslint/eslint-plugin": "^5.22.0",
    "@typescript-eslint/parser": "^5.22.0",
    "eslint": "^8.17.0",
    "eslint-config-prettier": "^8.5.0",
    "eslint-config-standard": "^17.0.0",
    "eslint-config-typescript": "^3.0.0",
    "eslint-plugin-import": "^2.26.0",
    "eslint-plugin-n": "^15.2.0",
    "eslint-plugin-prettier": "^4.0.0",
    "eslint-plugin-promise": "^6.0.0",
    "jest": "^28.1.0",
    "prettier": "^2.6.2",
    "ts-jest": "^28.0.5",
    "typescript": "^4.6.4"
  }

解决方案

错误核心是项目中仍存在依赖旧版fastify-static的插件，且部分Fastify生态插件未升级到适配v4的版本，按以下步骤修复：

彻底移除旧版fastify-static
执行命令删除旧依赖，避免版本冲突：

npm uninstall fastify-static
# 若使用yarn则执行：yarn remove fastify-static

升级所有适配Fastify v4的生态插件
你的依赖中有多个插件仍停留在适配v3的版本，需要升级到对应v4兼容版：
- @fastify/swagger：v6.x适配v3，需升级到v7.x+
- fastify-decorators：v3.x适配v3，需升级到v4.x+
- @fastify/redis：v5.x适配v3，需升级到v6.x+
执行批量升级命令：
```
npm install @fastify/swagger@latest fastify-decorators@latest @fastify/redis@latest
# yarn用户执行：yarn add @fastify/swagger@latest fastify-decorators@latest @fastify/redis@latest
```

清理缓存并重装依赖
残留的缓存可能导致旧版本依赖仍被引用，执行以下操作：

# npm用户
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

# yarn用户
yarn cache clean
rm -rf node_modules yarn.lock
yarn install

检查代码中的插件引用
确保代码中所有引用fastify-static的位置，都替换为新版的@fastify/static：
旧引用（CommonJS）：
```
const fastifyStatic = require('fastify-static')
```
新引用（CommonJS）：
```
const fastifyStatic = require('@fastify/static')
```
若使用ES模块：
```
import fastifyStatic from '@fastify/static'
```

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