迁移到 Express 5

¥Moving to Express 5

概述

Express 5 与 Express 4 没有太大区别；尽管它保留了相同的基本 API，但仍有一些变化破坏了与以前版本的兼容性。因此，如果你将使用 Express 4 构建的应用更新为使用 Express 5，则可能无法运行。

¥Express 5 is not very different from Express 4; although it maintains the same basic API, there are still changes that break compatibility with the previous version. Therefore, an application built with Express 4 might not work if you update it to use Express 5.

要安装此版本，你需要拥有 Node.js 18 或更高版本。然后，在你的应用目录中执行以下命令：

¥To install this version, you need to have a Node.js version 18 or higher. Then, execute the following command in your application directory:

npm install "express@5"

然后，你可以运行自动化测试以查看失败的原因，并根据下面列出的更新修复问题。解决测试失败后，运行你的应用以查看发生了什么错误。你会立即发现应用是否使用了不受支持的任何方法或属性。

¥You can then run your automated tests to see what fails, and fix problems according to the updates listed below. After addressing test failures, run your app to see what errors occur. You’ll find out right away if the app uses any methods or properties that are not supported.

Express 5 Codemods

为了帮助你迁移 Express 服务器，我们创建了一组 codemod，可帮助你自动将代码更新到最新版本的 Express。

¥To help you migrate your express server, we have created a set of codemods that will help you automatically update your code to the latest version of Express.

运行以下命令运行所有可用的 codemod：

¥Run the following command for run all the codemods available:

npx @expressjs/codemod upgrade

如果你想要运行特定的 codemod，可以运行以下命令：

¥If you want to run a specific codemod, you can run the following command:

npx @expressjs/codemod name-of-the-codemod

你可以找到可用的 codemods 此处 列表。

¥You can find the list of available codemods here.

Express 5 的变化

删除的方法和属性

¥Removed methods and properties

• app.del()
• app.param(fn)
• Pluralized method names
• Leading colon in name argument to app.param(name, fn)
• req.param(name)
• res.json(obj, status)
• res.jsonp(obj, status)
• res.redirect('back') and res.location('back')
• res.redirect(url, status)
• res.send(body, status)
• res.send(status)
• res.sendfile()
• express.static.mime
• express:router debug logs

变化

¥Changed

• Path route matching syntax
• Rejected promises handled from middleware and handlers
• express.urlencoded
• app.listen
• app.router
• req.body
• req.host
• req.query
• res.clearCookie
• res.status
• res.vary

改进

¥Improvements

• res.render()
• Brotli encoding support

删除的方法和属性

¥Removed methods and properties

如果你在应用中使用这些方法或属性中的任何一个，它都会崩溃。因此，你需要在更新到版本 5 后更改你的应用。

¥If you use any of these methods or properties in your app, it will crash. So, you’ll need to change your app after you update to version 5.

app.del()

Express 5 不再支持 app.del() 功能。如果你使用此功能，则会引发错误。要注册 HTTP DELETE 路由，请改用 app.delete() 函数。

¥Express 5 no longer supports the app.del() function. If you use this function, an error is thrown. For registering HTTP DELETE routes, use the app.delete() function instead.

最初，使用 del 代替 delete，因为 delete 是 JavaScript 中的保留关键字。但是，从 ECMAScript 6 开始，delete 和其他保留关键字可以合法地用作属性名称。

¥Initially, del was used instead of delete, because delete is a reserved keyword in JavaScript. However, as of ECMAScript 6, delete and other reserved keywords can legally be used as property names.

npx @expressjs/codemod v4-deprecated-signatures

// v4
app.del('/user/:id', (req, res) => {
  res.send(`DELETE /user/${req.params.id}`)
})

// v5
app.delete('/user/:id', (req, res) => {
  res.send(`DELETE /user/${req.params.id}`)
})

app.param(fn)

app.param(fn) 签名用于修改 app.param(name, fn) 函数的行为。它自 v4.11.0 起已被弃用，Express 5 根本不再支持它。

¥The app.param(fn) signature was used for modifying the behavior of the app.param(name, fn) function. It has been deprecated since v4.11.0, and Express 5 no longer supports it at all.

复数方法名称

以下方法名称已复数。在 Express 4 中，使用旧方法会导致弃用警告。Express 5 根本不再支持它们：

¥The following method names have been pluralized. In Express 4, using the old methods resulted in a deprecation warning. Express 5 no longer supports them at all:

req.acceptsCharset() 被 req.acceptsCharsets() 取代。

¥req.acceptsCharset() is replaced by req.acceptsCharsets().

req.acceptsEncoding() 被 req.acceptsEncodings() 取代。

¥req.acceptsEncoding() is replaced by req.acceptsEncodings().

req.acceptsLanguage() 被 req.acceptsLanguages() 取代。

¥req.acceptsLanguage() is replaced by req.acceptsLanguages().

npx @expressjs/codemod pluralized-methods

// v4
app.all('/', (req, res) => {
  req.acceptsCharset('utf-8')
  req.acceptsEncoding('br')
  req.acceptsLanguage('en')

  // ...
})

// v5
app.all('/', (req, res) => {
  req.acceptsCharsets('utf-8')
  req.acceptsEncodings('br')
  req.acceptsLanguages('en')

  // ...
})

app.param(name, fn) 名称中的前导冒号 (:)

app.param(name, fn) 函数名称中的前导冒号字符 (:) 是 Express 3 的残余，为了向后兼容，Express 4 通过弃用通知支持它。Express 5 将默默地忽略它并使用 name 参数而不用冒号作为前缀。

¥A leading colon character (:) in the name for the app.param(name, fn) function is a remnant of Express 3, and for the sake of backwards compatibility, Express 4 supported it with a deprecation notice. Express 5 will silently ignore it and use the name parameter without prefixing it with a colon.

如果你遵循 app.param 的 Express 4 文档，这不会影响你的代码，因为它没有提及前导冒号。

¥This should not affect your code if you follow the Express 4 documentation of app.param, as it makes no mention of the leading colon.

req.param(name)

这种检索表单数据的潜在混乱和危险方法已被删除。你现在需要专门在 req.params、req.body 或 req.query 对象中查找提交的参数名称。

¥This potentially confusing and dangerous method of retrieving form data has been removed. You will now need to specifically look for the submitted parameter name in the req.params, req.body, or req.query object.

npx @expressjs/codemod req-param

// v4
app.post('/user', (req, res) => {
  const id = req.param('id')
  const body = req.param('body')
  const query = req.param('query')

  // ...
})

// v5
app.post('/user', (req, res) => {
  const id = req.params.id
  const body = req.body
  const query = req.query

  // ...
})

res.json(obj, status)

Express 5 不再支持签名 res.json(obj, status)。相反，设置状态然后将其链接到 res.json() 方法，如下所示：res.status(status).json(obj)。

¥Express 5 no longer supports the signature res.json(obj, status). Instead, set the status and then chain it to the res.json() method like this: res.status(status).json(obj).

npx @expressjs/codemod v4-deprecated-signatures

// v4
app.post('/user', (req, res) => {
  res.json({ name: 'Ruben' }, 201)
})

// v5
app.post('/user', (req, res) => {
  res.status(201).json({ name: 'Ruben' })
})

res.jsonp(obj, status)

Express 5 不再支持签名 res.jsonp(obj, status)。相反，设置状态然后将其链接到 res.jsonp() 方法，如下所示：res.status(status).jsonp(obj)。

¥Express 5 no longer supports the signature res.jsonp(obj, status). Instead, set the status and then chain it to the res.jsonp() method like this: res.status(status).jsonp(obj).

npx @expressjs/codemod v4-deprecated-signatures

// v4
app.post('/user', (req, res) => {
  res.jsonp({ name: 'Ruben' }, 201)
})

// v5
app.post('/user', (req, res) => {
  res.status(201).jsonp({ name: 'Ruben' })
})

res.redirect(url, status)

Express 5 不再支持签名 res.redirect(url, status)。相反，使用以下签名：res.redirect(status, url)。

¥Express 5 no longer supports the signature res.redirect(url, status). Instead, use the following signature: res.redirect(status, url).

npx @expressjs/codemod v4-deprecated-signatures

// v4
app.get('/user', (req, res) => {
  res.redirect('/users', 301)
})

// v5
app.get('/user', (req, res) => {
  res.redirect(301, '/users')
})

res.redirect('back') and res.location('back')

Express 5 不再支持 res.redirect() 和 res.location() 方法中的魔法字符串 back。相反，使用 req.get('Referrer') || '/' 值重定向回上一页。在 Express 4 中，res.redirect('back') 和 res.location('back') 方法已被弃用。

¥Express 5 no longer supports the magic string back in the res.redirect() and res.location() methods. Instead, use the req.get('Referrer') || '/' value to redirect back to the previous page. In Express 4, the res.redirect('back') and res.location('back') methods were deprecated.

npx @expressjs/codemod magic-redirect

// v4
app.get('/user', (req, res) => {
  res.redirect('back')
})

// v5
app.get('/user', (req, res) => {
  res.redirect(req.get('Referrer') || '/')
})

res.send(body, status)

Express 5 不再支持签名 res.send(obj, status)。相反，设置状态然后将其链接到 res.send() 方法，如下所示：res.status(status).send(obj)。

¥Express 5 no longer supports the signature res.send(obj, status). Instead, set the status and then chain it to the res.send() method like this: res.status(status).send(obj).

npx @expressjs/codemod v4-deprecated-signatures

// v4
app.get('/user', (req, res) => {
  res.send({ name: 'Ruben' }, 200)
})

// v5
app.get('/user', (req, res) => {
  res.status(200).send({ name: 'Ruben' })
})

res.send(status)

Express 5 不再支持签名 res.send(status)，其中 status 是数字。相反，使用 res.sendStatus(statusCode) 函数，它设置 HTTP 响应标头状态代码并发送代码的文本版本：”未找到”、”内部服务器错误” 等等。如果你需要使用 res.send() 函数发送数字，请引用该数字以将其转换为字符串，以便 Express 不会将其解释为尝试使用不受支持的旧签名。

¥Express 5 no longer supports the signature res.send(status), where status is a number. Instead, use the res.sendStatus(statusCode) function, which sets the HTTP response header status code and sends the text version of the code: “Not Found”, “Internal Server Error”, and so on. If you need to send a number by using the res.send() function, quote the number to convert it to a string, so that Express does not interpret it as an attempt to use the unsupported old signature.

npx @expressjs/codemod v4-deprecated-signatures

// v4
app.get('/user', (req, res) => {
  res.send(200)
})

// v5
app.get('/user', (req, res) => {
  res.sendStatus(200)
})

res.sendfile()

Express 5 中的 res.sendfile() 功能已被驼峰式版本 res.sendFile() 取代。

¥The res.sendfile() function has been replaced by a camel-cased version res.sendFile() in Express 5.

npx @expressjs/codemod v4-deprecated-signatures

// v4
app.get('/user', (req, res) => {
  res.sendfile('/path/to/file')
})

// v5
app.get('/user', (req, res) => {
  res.sendFile('/path/to/file')
})

express.static.mime

在 Express 5 中，mime 不再是 static 字段的导出属性。使用 mime-types 包 处理 MIME 类型值。

¥In Express 5, mime is no longer an exported property of the static field. Use the mime-types package to work with MIME type values.

// v4
express.static.mime.lookup('json')

// v5
const mime = require('mime-types')
mime.lookup('json')

express:router 调试日志

在 Express 5 中，路由处理逻辑由依赖执行。因此，路由的调试日志不再在 express: 命名空间下可用。在 v4 中，日志在命名空间 express:router、express:router:layer 和 express:router:route 下可用。所有这些都包含在命名空间 express:* 下。在 v5.1+ 中，日志在命名空间 router、router:layer 和 router:route 下可用。来自 router:layer 和 router:route 的日志包含在命名空间 router:* 中。要在 v4 中使用 express:* 时实现相同的调试日志记录细节，请使用 express:*、router 和 router:* 的结合。

¥In Express 5, router handling logic is performed by a dependency. Therefore, the debug logs for the router are no longer available under the express: namespace. In v4, the logs were available under the namespaces express:router, express:router:layer, and express:router:route. All of these were included under the namespace express:*. In v5.1+, the logs are available under the namespaces router, router:layer, and router:route. The logs from router:layer and router:route are included in the namespace router:*. To achieve the same detail of debug logging when using express:* in v4, use a conjunction of express:*, router, and router:*.

# v4
DEBUG=express:* node index.js

# v5
DEBUG=express:*,router,router:* node index.js

变化

Path 路由匹配语法

路径路由匹配语法是指将字符串作为第一个参数提供给 app.all()、app.use()、app.METHOD()、router.all()、router.METHOD() 和 router.use() API。对路径字符串与传入请求的匹配方式进行了以下更改：

¥Path route matching syntax is when a string is supplied as the first parameter to the app.all(), app.use(), app.METHOD(), router.all(), router.METHOD(), and router.use() APIs. The following changes have been made to how the path string is matched to an incoming request:

• 通配符 * 必须有一个名称，与参数 : 的行为相匹配，使用 /*splat 而不是 /*

  ¥The wildcard * must have a name, matching the behavior of parameters :, use /*splat instead of /*

// v4
app.get('/*', async (req, res) => {
  res.send('ok')
})

// v5
app.get('/*splat', async (req, res) => {
  res.send('ok')
})

// v5
app.get('/{*splat}', async (req, res) => {
  res.send('ok')
})

• 可选字符 ? 不再受支持，请改用括号。

  ¥The optional character ? is no longer supported, use braces instead.

// v4
app.get('/:file.:ext?', async (req, res) => {
  res.send('ok')
})

// v5
app.get('/:file{.:ext}', async (req, res) => {
  res.send('ok')
})

• 不支持正则表达式字符。例如：

  ¥Regexp characters are not supported. For example:

app.get('/[discussion|page]/:slug', async (req, res) => {
  res.status(200).send('ok')
})

应更改为：

¥should be changed to:

app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => {
  res.status(200).send('ok')
})

• 为避免升级时产生混淆，部分字符已被保留（()[]?+!），请使用 \ 转义。

  ¥Some characters have been reserved to avoid confusion during upgrade (()[]?+!), use \ to escape them.

• 参数名称现在支持有效的 JavaScript 标识符，或像 :"this" 一样引用。

  ¥Parameter names now support valid JavaScript identifiers, or quoted like :"this".

从中间件和处理程序处理的被拒绝的 promise

现在，通过将被拒绝的值作为 Error 转发给错误处理中间件来处理返回被拒绝 promise 的请求中间件和处理程序。这意味着使用 async 函数作为中间件和处理程序比以往任何时候都容易。当 async 函数中抛出错误或异步函数内拒绝的 Promise 为 await 时，这些错误将被传递到错误处理程序，就像调用 next(err) 一样。

¥Request middleware and handlers that return rejected promises are now handled by forwarding the rejected value as an Error to the error handling middleware. This means that using async functions as middleware and handlers are easier than ever. When an error is thrown in an async function or a rejected promise is awaited inside an async function, those errors will be passed to the error handler as if calling next(err).

Express 如何处理错误的详细信息在 错误处理文档 中进行了介绍。

¥Details of how Express handles errors is covered in the error handling documentation.

express.urlencoded

express.urlencoded 方法默认将 extended 选项设为 false。

¥The express.urlencoded method makes the extended option false by default.

app.listen

在 Express 5 中，当服务器收到错误事件时，app.listen 方法将调用用户提供的回调函数（如果提供）。在 Express 4 中，会抛出此类错误。此更改将错误处理责任转移到 Express 5 中的回调函数。如果出现错误，它将作为参数传递给回调。例如：

¥In Express 5, the app.listen method will invoke the user-provided callback function (if provided) when the server receives an error event. In Express 4, such errors would be thrown. This change shifts error-handling responsibility to the callback function in Express 5. If there is an error, it will be passed to the callback as an argument. For example:

const server = app.listen(8080, '0.0.0.0', (error) => {
  if (error) {
    throw error // e.g. EADDRINUSE
  }
  console.log(`Listening on ${JSON.stringify(server.address())}`)
})

app.router

在 Express 4 中删除的 app.router 对象在 Express 5 中卷土重来。在新版本中，此对象只是对基本 Express 路由的引用，这与 Express 3 中的应用必须显式加载它不同。

¥The app.router object, which was removed in Express 4, has made a comeback in Express 5. In the new version, this object is a just a reference to the base Express router, unlike in Express 3, where an app had to explicitly load it.

req.body

当主体尚未解析时，req.body 属性将返回 undefined。在 Express 4 中，它默认返回 {}。

¥The req.body property returns undefined when the body has not been parsed. In Express 4, it returns {} by default.

req.host

在 Express 4 中，如果端口号存在，req.host 函数会错误地剥离端口号。在 Express 5 中，端口号保持不变。

¥In Express 4, the req.host function incorrectly stripped off the port number if it was present. In Express 5, the port number is maintained.

req.query

req.query 属性不再是可写属性，而是一个 getter。默认查询解析器已从 “extended” 更改为 “simple”。

¥The req.query property is no longer a writable property and is instead a getter. The default query parser has been changed from “extended” to “simple”.

res.clearCookie

res.clearCookie 方法会忽略用户提供的 maxAge 和 expires 选项。

¥The res.clearCookie method ignores the maxAge and expires options provided by the user.

res.status

res.status 方法仅接受 100 到 999 范围内的整数，遵循 Node.js 定义的行为，当状态代码不是整数时会返回错误。

¥The res.status method only accepts integers in the range of 100 to 999, following the behavior defined by Node.js, and it returns an error when the status code is not an integer.

res.vary

当缺少 field 参数时，res.vary 将抛出错误。在 Express 4 中，如果省略了参数，它会在控制台中发出警告

¥The res.vary throws an error when the field argument is missing. In Express 4, if the argument was omitted, it gave a warning in the console

改进

¥Improvements

res.render()

此方法现在对所有视图引擎强制执行异步行为，避免由具有同步实现且违反推荐接口的视图引擎引起的错误。

¥This method now enforces asynchronous behavior for all view engines, avoiding bugs caused by view engines that had a synchronous implementation and that violated the recommended interface.

Brotli 编码支持

Express 5 支持 Brotli 编码，用于从支持它的客户端接收的请求。

¥Express 5 supports Brotli encoding for requests received from clients that support it.