Version 3 and before of Fastify are no longer maintained.
For information about support options for end-of-life versions, see the Long Term Support page.V5 迁移指南
¥V5 Migration Guide
本指南旨在帮助从 Fastify v4 迁移到 v5。
¥This guide is intended to help with migration from Fastify v4 to v5.
在迁移到 v5 之前,请确保你已修复 v4 中的所有弃用警告。所有 v4 弃用都已删除,升级后将不再起作用。
¥Before migrating to v5, please ensure that you have fixed all deprecation warnings from v4. All v4 deprecations have been removed and will no longer work after upgrading.
长期支持周期
¥Long Term Support Cycle
Fastify v5 仅支持 Node.js v20+。如果你使用的是旧版本的 Node.js,则需要升级到较新版本才能使用 Fastify v5。
¥Fastify v5 will only support Node.js v20+. If you are using an older version of Node.js, you will need to upgrade to a newer version to use Fastify v5.
Fastify v4 仍受支持至 2025 年 6 月 30 日。如果你无法升级,你应该考虑从 HeroDevs 购买终止支持计划。
¥Fastify v4 is still supported until June 30, 2025. If you are unable to upgrade, you should consider buying an end-of-life support plan from HeroDevs.
为什么是 Node.js v20?
¥Why Node.js v20?
Fastify v5 将仅支持 Node.js v20+,因为它与 v18 相比有显著差异,例如对 node:test
的更好支持。这使我们能够提供更好的开发者体验并简化维护。
¥Fastify v5 will only support Node.js v20+ because it has significant differences
compared to v18, such as
better support for node:test
. This allows us to provide a better developer
experience and streamline maintenance.
Node.js v18 将于 2025 年 4 月 30 日退出长期支持,因此你无论如何都应该计划升级到 v20。
¥Node.js v18 will exit Long Term Support on April 30, 2025, so you should be planning to upgrade to v20 anyway.
重大变更
¥Breaking Changes
现在需要完整的 JSON 模式来处理 querystring
、params
和 body
以及响应模式
¥Full JSON Schema is now required for querystring
, params
and body
and response schemas
从 v5 开始,Fastify 将需要完整的 JSON 模式来满足 querystring
、params
和 body
模式的要求。请注意,jsonShortHand
选项也已被删除。
¥Starting with v5, Fastify will require a full JSON schema for the querystring
,
params
and body
schema. Note that the jsonShortHand
option has been
removed as well.
如果使用默认的 JSON 模式验证器,则需要为 querystring
、params
、body
和 response
模式提供完整的 JSON 模式,包括 type
属性。
¥If the default JSON Schema validator is used, you will need
to provide a full JSON schema for the
querystring
, params
, body
, and response
schemas,
including the type
property.
// v4
fastify.get('/route', {
schema: {
querystring: {
name: { type: 'string' }
}
}
}, (req, reply) => {
reply.send({ hello: req.query.name });
});
// v5
fastify.get('/route', {
schema: {
querystring: {
type: 'object',
properties: {
name: { type: 'string' }
},
required: ['name']
}
}
}, (req, reply) => {
reply.send({ hello: req.query.name });
});
有关更多详细信息,请参阅 #5586
¥See #5586 for more details
请注意,仍然可以覆盖 JSON Schema 验证器以使用不同的格式,例如 Zod。此更改也简化了这一点。
¥Note that it's still possible to override the JSON Schema validator to use a different format, such as Zod. This change simplifies that as well.
此更改有助于集成其他工具,例如 @fastify/swagger
。
¥This change helps with integration of other tools, such as
@fastify/swagger
.
新的日志器构造函数签名
¥New logger constructor signature
在 Fastify v4 中,Fastify 接受了在 logger
选项中构建 pino 日志器的选项,以及自定义日志器实例。这是造成严重混乱的根源。
¥In Fastify v4, Fastify accepted the options to build a pino
logger in the logger
option, as well as a custom logger instance.
This was the source of significant confusion.
因此,logger
选项在 v5 中将不再接受自定义日志器。要使用自定义日志器,你应该改用 loggerInstance
选项:
¥As a result, the logger
option will not accept a custom logger anymore in v5.
To use a custom logger, you should use the loggerInstance
option instead:
// v4
const logger = require('pino')();
const fastify = require('fastify')({
logger
});
// v5
const loggerInstance = require('pino')();
const fastify = require('fastify')({
loggerInstance
});
useSemicolonDelimiter
默认为 false
¥useSemicolonDelimiter
false by default
从 v5 开始,Fastify 实例将不再默认支持在查询字符串中使用分号分隔符,就像在 v4 中一样。这是因为它是非标准行为并且不遵守 RFC 3986。
¥Starting with v5, Fastify instances will no longer default to supporting the use of semicolon delimiters in the query string as they did in v4. This is due to it being non-standard behavior and not adhering to RFC 3986.
如果你仍希望使用分号作为分隔符,则可以通过在服务器配置中设置 useSemicolonDelimiter: true
来实现。
¥If you still wish to use semicolons as delimiters, you can do so by
setting useSemicolonDelimiter: true
in the server configuration.
const fastify = require('fastify')({
useSemicolonDelimiter: true
});
参数对象不再具有原型
¥The parameters object no longer has a prototype
在 v4 中,parameters
对象有一个原型。这在 v5 中不再是这种情况。这意味着你无法再访问 parameters
对象上从 Object
继承的属性,例如 toString
或 hasOwnProperty
。
¥In v4, the parameters
object had a prototype. This is no longer the case in v5.
This means that you can no longer access properties inherited from Object
on
the parameters
object, such as toString
or hasOwnProperty
.
// v4
fastify.get('/route/:name', (req, reply) => {
console.log(req.params.hasOwnProperty('name')); // true
return { hello: req.params.name };
});
// v5
fastify.get('/route/:name', (req, reply) => {
console.log(Object.hasOwn(req.params, 'name')); // true
return { hello: req.params.name };
});
通过加强对原型污染攻击的防御,这提高了应用的安全性。
¥This increases the security of the application by hardening against prototype pollution attacks.
类型提供程序现在区分验证器和序列化器模式
¥Type Providers now differentiate between validator and serializer schemas
在 v4 中,类型提供程序对于验证和序列化具有相同的类型。在 v5 中,类型提供程序已分为两种不同的类型:ValidatorSchema
和 SerializerSchema
。
¥In v4, the type providers had the same types for both validation and serialization.
In v5, the type providers have been split into two separate types: ValidatorSchema
and SerializerSchema
.
@fastify/type-provider-json-schema-to-ts
和 @fastify/type-provider-typebox
已更新:升级到最新版本以获取新类型。如果你使用的是自定义类型提供程序,则需要按如下方式进行修改:
¥@fastify/type-provider-json-schema-to-ts
and
@fastify/type-provider-typebox
have already been updated: upgrade to the latest version to get the new types.
If you are using a custom type provider, you will need to modify it like
the following:
--- a/index.ts
+++ b/index.ts
@@ -11,7 +11,8 @@ import {
import { FromSchema, FromSchemaDefaultOptions, FromSchemaOptions, JSONSchema } from 'json-schema-to-ts'
export interface JsonSchemaToTsProvider<
Options extends FromSchemaOptions = FromSchemaDefaultOptions
> extends FastifyTypeProvider {
- output: this['input'] extends JSONSchema ? FromSchema<this['input'], Options> : unknown;
+ validator: this['schema'] extends JSONSchema ? FromSchema<this['schema'], Options> : unknown;
+ serializer: this['schema'] extends JSONSchema ? FromSchema<this['schema'], Options> : unknown;
}
.listen() 方法的更改
¥Changes to the .listen() method
.listen()
方法的可变参数签名已被删除。这意味着你无法再使用可变数量的参数调用 .listen()
。
¥The variadic argument signature of the .listen()
method has been removed.
This means that you can no longer call .listen()
with a variable number of arguments.
// v4
fastify.listen(8000)
将成为:
¥Will become:
// v5
fastify.listen({ port: 8000 })
这在 v4 中已弃用为 FSTDEP011
,因此你 应该已经更新了代码以使用新签名。
¥This was already deprecated in v4 as FSTDEP011
, so you should have already updated
your code to use the new signature.
已删除直接返回尾部
¥Direct return of trailers has been removed
在 v4 中,你可以直接从处理程序返回尾部。这在 v5 中不再可能。
¥In v4, you could directly return trailers from a handler. This is no longer possible in v5.
// v4
fastify.get('/route', (req, reply) => {
reply.trailer('ETag', function (reply, payload) {
return 'custom-etag'
})
reply.send('')
});
// v5
fastify.get('/route', (req, reply) => {
reply.trailer('ETag', async function (reply, payload) {
return 'custom-etag'
})
reply.send('')
});
也可以使用回调。这在 v4 中已弃用为 FSTDEP013
,因此你应该已经更新了代码以使用新签名。
¥A callback could also be used.
This was already deprecated in v4 as FSTDEP013
,
so you should have already updated your code to use the new signature.