5.x API

express.json([options])  express.json([选项])

This is a built-in middleware function in Express. It parses incoming requests with JSON payloads and is based on body-parser.
这是 Express 中的一个内置中间件函数。它解析带有 JSON 负载的传入请求，基于 body-parser。

Returns middleware that only parses JSON and only looks at requests where the Content-Type header matches the type option. This parser accepts any Unicode encoding of the body and supports automatic inflation of gzip and deflate encodings.
返回一个仅解析 JSON 且仅查看请求头 Content-Type 与选项 type 匹配的中间件。该解析器接受任何 Unicode 编码的请求体，并支持自动解压 gzip 和 deflate 编码。

A new body object containing the parsed data is populated on the request object after the middleware (i.e. req.body), or undefined if there was no body to parse, the Content-Type was not matched, or an error occurred.
中间件（即 req.body ）执行后，一个新的 body 对象会被填充到 request 对象中，其中包含解析后的数据；若无请求体可解析、 Content-Type 未匹配或发生错误，则填充 undefined 。

The following table describes the properties of the optional options object.
下表描述了可选对象 options 的属性。

express.raw([options])  express.raw([选项])

This is a built-in middleware function in Express. It parses incoming request payloads into a Buffer and is based on body-parser.
这是 Express 中的一个内置中间件函数。它将传入的请求负载解析为 Buffer ，并基于 body-parser。

Returns middleware that parses all bodies as a Buffer and only looks at requests where the Content-Type header matches the type option. This parser accepts any Unicode encoding of the body and supports automatic inflation of gzip and deflate encodings.
返回一个中间件，该中间件将所有请求体解析为 Buffer ，并且仅处理 Content-Type 请求头与 type 选项匹配的请求。此解析器接受任何 Unicode 编码的请求体，并支持自动解压 gzip 和 deflate 编码。

A new body Buffer containing the parsed data is populated on the request object after the middleware (i.e. req.body), or undefined if there was no body to parse, the Content-Type was not matched, or an error occurred.
中间件执行后（即 req.body ），会在 request 对象上填充一个包含解析数据的新 body Buffer ，如果没有可解析的请求体、 Content-Type 不匹配或发生错误，则填充 undefined 。

The following table describes the properties of the optional options object.
下表描述了可选 options 对象的属性。

express.Router([options])
express.Router([选项])

Creates a new router object.
创建一个新的路由器对象。

const router = express.Router([options])

The optional options parameter specifies the behavior of the router.
可选的 options 参数指定了路由器的行为。

You can add middleware and HTTP method routes (such as get, put, post, and so on) to router just like an application.
你可以像应用程序一样，向 router 添加中间件和 HTTP 方法路由（例如 get 、 put 、 post 等）。

For more information, see Router.
更多信息，请参阅路由器文档。

express.static(root, [options])

This is a built-in middleware function in Express. It serves static files and is based on serve-static.
这是 Express 中的一个内置中间件函数。它用于提供静态文件服务，基于 serve-static。

The root argument specifies the root directory from which to serve static assets. The function determines the file to serve by combining req.url with the provided root directory. When a file is not found, instead of sending a 404 response, it instead calls next() to move on to the next middleware, allowing for stacking and fall-backs.
参数 root 指定了提供静态资源的根目录。该函数通过将 req.url 与提供的 root 目录结合来确定要服务的文件。当文件未找到时，它不会发送 404 响应，而是调用 next() 以继续执行下一个中间件，从而实现堆叠和回退机制。

The following table describes the properties of the options object. See also the example below.
下表描述了 options 对象的属性。另请参阅下方的示例。

For more information, see Serving static files in Express. and Using middleware - Built-in middleware.
更多信息，请参阅 Express 中的静态文件服务和使用中间件 - 内置中间件。

dotfiles  点文件

Possible values for this option are:
此选项的可能值为：

• “allow” - No special treatment for dotfiles.
  “allow” - 对点文件不做特殊处理。
• “deny” - Deny a request for a dotfile, respond with 403, then call next().
  “deny” - 拒绝点文件请求，响应为 403 ，然后调用 next() 。
• “ignore” - Act as if the dotfile does not exist, respond with 404, then call next().
  “ignore” - 假装点文件不存在，响应为 404 ，然后调用 next() 。

fallthrough

When this option is true, client errors such as a bad request or a request to a non-existent file will cause this middleware to simply call next() to invoke the next middleware in the stack. When false, these errors (even 404s), will invoke next(err).
当此选项为 true 时，客户端错误如错误请求或请求不存在的文件将导致此中间件仅调用 next() 以触发堆栈中的下一个中间件。若为 false，这些错误（包括 404）将触发 next(err) 。

Set this option to true so you can map multiple physical directories to the same web address or for routes to fill in non-existent files.
将此选项设置为 true ，以便您可以将多个物理目录映射到相同的网络地址，或让路由填充不存在的文件。

Use false if you have mounted this middleware at a path designed to be strictly a single file system directory, which allows for short-circuiting 404s for less overhead. This middleware will also reply to all methods.
如果您已将此中间件挂载在严格设计为单一文件系统目录的路径上，请使用 false ，这样可以短路 404 错误以减少开销。此中间件还将响应所有方法。

setHeaders  设置头部

For this option, specify a function to set custom response headers. Alterations to the headers must occur synchronously.
对于此选项，指定一个函数来设置自定义响应头部。对头部的修改必须同步进行。

The signature of the function is:
函数的签名为：

fn(res, path, stat)

Arguments:  参数：

• res, the response object.
  res ，响应对象。
• path, the file path that is being sent.
  path ，正在发送的文件路径。
• stat, the stat object of the file that is being sent.
  stat ，正在发送的文件的 stat 对象。

Example of express.static
express.static 的示例

Here is an example of using the express.static middleware function with an elaborate options object:
这里是一个使用 express.static 中间件函数配合详细选项对象的示例：

const options = {
  dotfiles: 'ignore',
  etag: false,
  extensions: ['htm', 'html'],
  index: false,
  maxAge: '1d',
  redirect: false,
  setHeaders (res, path, stat) {
    res.set('x-timestamp', Date.now())
  }
}

app.use(express.static('public', options))

express.text([options])  express.text([选项])

This is a built-in middleware function in Express. It parses incoming request payloads into a string and is based on body-parser.
这是 Express 中的一个内置中间件函数。它将传入的请求负载解析为字符串，并基于 body-parser。

Returns middleware that parses all bodies as a string and only looks at requests where the Content-Type header matches the type option. This parser accepts any Unicode encoding of the body and supports automatic inflation of gzip and deflate encodings.
返回一个中间件，该中间件将所有请求体解析为字符串，并且仅处理 Content-Type 头部与 type 选项匹配的请求。此解析器接受任何 Unicode 编码的请求体，并支持自动解压 gzip 和 deflate 编码。

A new body string containing the parsed data is populated on the request object after the middleware (i.e. req.body), or undefined if there was no body to parse, the Content-Type was not matched, or an error occurred.
中间件处理后（即 req.body ），会在 request 对象上填充一个包含解析数据的新 body 字符串；如果没有可解析的请求体、 Content-Type 不匹配或发生错误，则为 undefined 。

The following table describes the properties of the optional options object.
下表描述了可选 options 对象的属性。

express.urlencoded([options])
express.urlencoded([选项])

This is a built-in middleware function in Express. It parses incoming requests with urlencoded payloads and is based on body-parser.
这是 Express 中的一个内置中间件函数。它解析带有 urlencoded 负载的传入请求，并基于 body-parser。

Returns middleware that only parses urlencoded bodies and only looks at requests where the Content-Type header matches the type option. This parser accepts only UTF-8 encoding of the body and supports automatic inflation of gzip and deflate encodings.
返回一个仅解析 urlencoded 请求体且仅查看请求头 Content-Type 与选项 type 匹配的中间件。此解析器仅接受 UTF-8 编码的请求体，并支持自动解压 gzip 和 deflate 编码。

A new body object containing the parsed data is populated on the request object after the middleware (i.e. req.body), or undefined if there was no body to parse, the Content-Type was not matched, or an error occurred. This object will contain key-value pairs, where the value can be a string or array (when extended is false), or any type (when extended is true).
中间件执行后（即 req.body ），一个新的 body 对象包含解析后的数据会被填充到 request 对象上，若无请求体可解析、 Content-Type 未匹配或发生错误，则为 undefined 。此对象将包含键值对，其中值可以是字符串或数组（当 extended 为 false 时），或任意类型（当 extended 为 true 时）。

The following table describes the properties of the optional options object.
下表描述了可选 options 对象的属性。

app.locals

The app.locals object has properties that are local variables within the application, and will be available in templates rendered with res.render.
app.locals 对象拥有作为应用程序内局部变量的属性，这些属性将在使用 res.render 渲染的模板中可用。

console.dir(app.locals.title)
// => 'My App'

console.dir(app.locals.email)
// => 'me@myapp.com'

Once set, the value of app.locals properties persist throughout the life of the application, in contrast with res.locals properties that are valid only for the lifetime of the request.
一旦设置， app.locals 属性的值将在应用程序的整个生命周期中持续存在，这与仅在请求生命周期内有效的 res.locals 属性形成对比。

You can access local variables in templates rendered within the application. This is useful for providing helper functions to templates, as well as application-level data. Local variables are available in middleware via req.app.locals (see req.app)
您可以在应用程序内渲染的模板中访问局部变量。这对于向模板提供辅助函数以及应用级数据非常有用。局部变量可通过 req.app.locals 在中间件中访问（参见 req.app）。

app.locals.title = 'My App'
app.locals.strftime = require('strftime')
app.locals.email = 'me@myapp.com'

app.mountpath

The app.mountpath property contains one or more path patterns on which a sub-app was mounted.
app.mountpath 属性包含一个或多个子应用挂载的路径模式。

const express = require('express')

const app = express() // the main app
const admin = express() // the sub app

admin.get('/', (req, res) => {
  console.log(admin.mountpath) // /admin
  res.send('Admin Homepage')
})

app.use('/admin', admin) // mount the sub app

It is similar to the baseUrl property of the req object, except req.baseUrl returns the matched URL path, instead of the matched patterns.
这与 req 对象的 baseUrl 属性类似，不同之处在于 req.baseUrl 返回的是匹配的 URL 路径，而非匹配的模式。

If a sub-app is mounted on multiple path patterns, app.mountpath returns the list of patterns it is mounted on, as shown in the following example.
如果一个子应用挂载在多个路径模式上， app.mountpath 会返回其挂载的所有模式列表，如下例所示。

const admin = express()

admin.get('/', (req, res) => {
  console.log(admin.mountpath) // [ '/adm{*splat}n', '/manager' ]
  res.send('Admin Homepage')
})

const secret = express()
secret.get('/', (req, res) => {
  console.log(secret.mountpath) // /secr{*splat}t
  res.send('Admin Secret')
})

admin.use('/secr{*splat}t', secret) // load the 'secret' router on '/secr{*splat}t', on the 'admin' sub app
app.use(['/adm{*splat}n', '/manager'], admin) // load the 'admin' router on '/adm{*splat}n' and '/manager', on the parent app

app.router

The application’s in-built instance of router. This is created lazily, on first access.
应用程序内置的路由器实例。此实例在首次访问时延迟创建。

const express = require('express')
const app = express()
const router = app.router

router.get('/', (req, res) => {
  res.send('hello world')
})

app.listen(3000)

You can add middleware and HTTP method routes to the router just like an application.
您可以像对待应用程序一样，向 router 添加中间件和 HTTP 方法路由。

For more information, see Router.
更多信息，请参阅 Router。

app.on('mount', callback(parent))

The mount event is fired on a sub-app, when it is mounted on a parent app. The parent app is passed to the callback function.
当子应用挂载到父应用上时，会触发 mount 事件。父应用会被传递给回调函数。

const admin = express()

admin.on('mount', (parent) => {
  console.log('Admin Mounted')
  console.log(parent) // refers to the parent app
})

admin.get('/', (req, res) => {
  res.send('Admin Homepage')
})

app.use('/admin', admin)

app.all(path, callback [, callback ...])

This method is like the standard app.METHOD() methods, except it matches all HTTP verbs.
此方法与标准的 app.METHOD() 方法类似，但它匹配所有的 HTTP 动词。

Arguments  参数

Examples  示例

The following callback is executed for requests to /secret whether using GET, POST, PUT, DELETE, or any other HTTP request method:
无论使用 GET、POST、PUT、DELETE 还是其他任何 HTTP 请求方法，以下回调都会针对 /secret 的请求执行：

app.all('/secret', (req, res, next) => {
  console.log('Accessing the secret section ...')
  next() // pass control to the next handler
})

The app.all() method is useful for mapping “global” logic for specific path prefixes or arbitrary matches. For example, if you put the following at the top of all other route definitions, it requires that all routes from that point on require authentication, and automatically load a user. Keep in mind that these callbacks do not have to act as end-points: loadUser can perform a task, then call next() to continue matching subsequent routes.
app.all() 方法对于为特定路径前缀或任意匹配映射“全局”逻辑非常有用。例如，如果你在所有其他路由定义的最前面放置以下代码，它将要求从该点开始的所有路由都需要认证，并自动加载用户。请记住，这些回调不必作为端点： loadUser 可以执行一个任务，然后调用 next() 以继续匹配后续路由。

app.all('{*splat}', requireAuthentication, loadUser)

Or the equivalent:  或等效于：

app.all('{*splat}', requireAuthentication)
app.all('{*splat}', loadUser)

Another example is white-listed “global” functionality. The example is similar to the ones above, but it only restricts paths that start with “/api”:
另一个例子是白名单中的“全局”功能。此示例与上述类似，但仅限制以“/api”开头的路径：

app.all('/api/{*splat}', requireAuthentication)

app.delete(path, callback [, callback ...])

Routes HTTP DELETE requests to the specified path with the specified callback functions. For more information, see the routing guide.
将 HTTP DELETE 请求路由到指定路径，并使用指定的回调函数。更多信息，请参阅路由指南。

Arguments  参数

Example  示例

app.delete('/', (req, res) => {
  res.send('DELETE request to homepage')
})

app.disable(name)

Sets the Boolean setting name to false, where name is one of the properties from the app settings table. Calling app.set('foo', false) for a Boolean property is the same as calling app.disable('foo').
将布尔设置 name 设为 false ，其中 name 是应用设置表中的属性之一。对布尔属性调用 app.set('foo', false) 等同于调用 app.disable('foo') 。

For example:  例如：

app.disable('trust proxy')
app.get('trust proxy')
// => false

app.disabled(name)

Returns true if the Boolean setting name is disabled (false), where name is one of the properties from the app settings table.
如果布尔设置 name 被禁用（ false ），则返回 true ，其中 name 是应用设置表中的属性之一。

app.disabled('trust proxy')
// => true

app.enable('trust proxy')
app.disabled('trust proxy')
// => false

app.enable(name)

Sets the Boolean setting name to true, where name is one of the properties from the app settings table. Calling app.set('foo', true) for a Boolean property is the same as calling app.enable('foo').
将布尔设置 name 设为 true ，其中 name 是应用设置表中的属性之一。对布尔属性调用 app.set('foo', true) 等同于调用 app.enable('foo') 。

app.enable('trust proxy')
app.get('trust proxy')
// => true

app.enabled(name)

Returns true if the setting name is enabled (true), where name is one of the properties from the app settings table.
如果设置 name 已启用（ true ），则返回 true ，其中 name 是应用设置表中的属性之一。

app.enabled('trust proxy')
// => false

app.enable('trust proxy')
app.enabled('trust proxy')
// => true

app.engine(ext, callback)

Registers the given template engine callback as ext.
将给定的模板引擎 callback 注册为 ext 。

By default, Express will require() the engine based on the file extension. For example, if you try to render a “foo.pug” file, Express invokes the following internally, and caches the require() on subsequent calls to increase performance.
默认情况下，Express 会根据文件扩展名 require() 引擎。例如，若尝试渲染“foo.pug”文件，Express 内部会调用以下内容，并在后续调用中缓存 require() 以提高性能。

app.engine('pug', require('pug').__express)

Use this method for engines that do not provide .__express out of the box, or if you wish to “map” a different extension to the template engine.
对于不提供开箱即用 .__express 的引擎，或希望将不同扩展名“映射”到模板引擎时，可使用此方法。

For example, to map the EJS template engine to “.html” files:
例如，将 EJS 模板引擎映射到“.html”文件：

app.engine('html', require('ejs').renderFile)

In this case, EJS provides a .renderFile() method with the same signature that Express expects: (path, options, callback), though note that it aliases this method as ejs.__express internally so if you’re using “.ejs” extensions you don’t need to do anything.
在此情况下，EJS 提供了一个与 Express 预期签名相同的 .renderFile() 方法： (path, options, callback) ，但请注意，它在内部将此方法别名为 ejs.__express ，因此若使用“.ejs”扩展名则无需额外操作。

Some template engines do not follow this convention. The consolidate.js library maps Node template engines to follow this convention, so they work seamlessly with Express.
部分模板引擎并不遵循这一惯例。consolidate.js 库将 Node 模板引擎映射为遵循此惯例，以便它们能与 Express 无缝协作。

const engines = require('consolidate')
app.engine('haml', engines.haml)
app.engine('html', engines.hogan)

app.get(name)

Returns the value of name app setting, where name is one of the strings in the app settings table. For example:
返回@app 设置的值，其中 name 是应用设置表中的字符串之一。例如：

app.get('title')
// => undefined

app.set('title', 'My Site')
app.get('title')
// => "My Site"

app.get(path, callback [, callback ...])

Routes HTTP GET requests to the specified path with the specified callback functions.
将 HTTP GET 请求路由到指定路径，并执行相应的回调函数。

Arguments  参数

For more information, see the routing guide.
更多信息，请参阅路由指南。

Example  示例

app.get('/', (req, res) => {
  res.send('GET request to homepage')
})

app.listen(path, [callback])

Starts a UNIX socket and listens for connections on the given path. This method is identical to Node’s http.Server.listen().
启动一个 UNIX 套接字并在指定路径上监听连接。此方法与 Node 的 http.Server.listen()相同。

const express = require('express')
const app = express()
app.listen('/tmp/sock')

app.listen([port[, host[, backlog]]][, callback])
app.listen([端口[, 主机[, 积压数]]][, 回调函数])

Binds and listens for connections on the specified host and port. This method is identical to Node’s http.Server.listen().
在指定的主机和端口上绑定并监听连接。此方法与 Node 的 http.Server.listen()相同。

If port is omitted or is 0, the operating system will assign an arbitrary unused port, which is useful for cases like automated tasks (tests, etc.).
如果省略端口或设为 0，操作系统将分配任意一个未使用的端口，这对于自动化任务（如测试等）场景非常有用。

const express = require('express')
const app = express()
app.listen(3000)

The app returned by express() is in fact a JavaScript Function, designed to be passed to Node’s HTTP servers as a callback to handle requests. This makes it easy to provide both HTTP and HTTPS versions of your app with the same code base, as the app does not inherit from these (it is simply a callback):
express() 返回的 app 实际上是一个 JavaScript Function ，设计用于作为回调传递给 Node 的 HTTP 服务器以处理请求。这使得用相同的代码库提供 HTTP 和 HTTPS 版本的应用程序变得容易，因为应用程序并不继承这些（它只是一个回调）：

const express = require('express')
const https = require('https')
const http = require('http')
const app = express()

http.createServer(app).listen(80)
https.createServer(options, app).listen(443)

The app.listen() method returns an http.Server object and (for HTTP) is a convenience method for the following:
app.listen() 方法返回一个 http.Server 对象，并且（对于 HTTP）是以下操作的便捷方法：

app.listen = function () {
  const server = http.createServer(this)
  return server.listen.apply(server, arguments)
}

app.METHOD(path, callback [, callback ...])
app.METHOD(路径, 回调函数 [, 回调函数 ...])

Routes an HTTP request, where METHOD is the HTTP method of the request, such as GET, PUT, POST, and so on, in lowercase. Thus, the actual methods are app.get(), app.post(), app.put(), and so on. See Routing methods below for the complete list.
路由一个 HTTP 请求，其中 METHOD 是该请求的 HTTP 方法，如 GET、PUT、POST 等，均为小写。因此，实际的方法包括 app.get() 、 app.post() 、 app.put() 等。完整列表请参见下方的路由方法。

Arguments  参数

Routing methods  路由方法

Express supports the following routing methods corresponding to the HTTP methods of the same names:
Express 支持以下路由方法，对应同名的 HTTP 方法：

The API documentation has explicit entries only for the most popular HTTP methods app.get(), app.post(), app.put(), and app.delete(). However, the other methods listed above work in exactly the same way.
API 文档仅明确记录了最流行的 HTTP 方法 app.get() 、 app.post() 、 app.put() 和 app.delete() 。然而，上面列出的其他方法以完全相同的方式工作。

To route methods that translate to invalid JavaScript variable names, use the bracket notation. For example, app['m-search']('/', function ....
要路由那些转换为无效 JavaScript 变量名的方法，请使用括号表示法。例如， app['m-search']('/', function ... 。

The method, app.all(), is not derived from any HTTP method and loads middleware at the specified path for all HTTP request methods. For more information, see app.all.
方法 app.all() 并非源自任何 HTTP 方法，它会为所有 HTTP 请求方法在指定路径加载中间件。更多信息，请参阅 app.all。

For more information on routing, see the routing guide.
有关路由的更多信息，请参阅路由指南。

app.param(name, callback)
app.param(名称, 回调函数)

Add callback triggers to route parameters, where name is the name of the parameter or an array of them, and callback is the callback function. The parameters of the callback function are the request object, the response object, the next middleware, the value of the parameter and the name of the parameter, in that order.
向路由参数添加回调触发器，其中 name 是参数名称或其数组， callback 是回调函数。回调函数的参数依次为请求对象、响应对象、下一个中间件、参数值及参数名称。

If name is an array, the callback trigger is registered for each parameter declared in it, in the order in which they are declared. Furthermore, for each declared parameter except the last one, a call to next inside the callback will call the callback for the next declared parameter. For the last parameter, a call to next will call the next middleware in place for the route currently being processed, just like it would if name were just a string.
如果 name 是一个数组，那么 callback 触发器会按照声明的顺序为其中每个参数注册。此外，对于除最后一个参数外的每个声明参数，回调内部调用 next 将会触发下一个声明参数的回调。对于最后一个参数，调用 next 则会调用当前处理路由的下一个中间件，就像 name 仅是一个字符串时那样。

For example, when :user is present in a route path, you may map user loading logic to automatically provide req.user to the route, or perform validations on the parameter input.
例如，当路由路径中存在 :user 时，你可以将用户加载逻辑映射到该路由，自动提供 req.user ，或对参数输入执行验证。

app.param('user', (req, res, next, id) => {
  // try to get the user details from the User model and attach it to the request object
  User.find(id, (err, user) => {
    if (err) {
      next(err)
    } else if (user) {
      req.user = user
      next()
    } else {
      next(new Error('failed to load user'))
    }
  })
})

Param callback functions are local to the router on which they are defined. They are not inherited by mounted apps or routers, nor are they triggered for route parameters inherited from parent routers. Hence, param callbacks defined on app will be triggered only by route parameters defined on app routes.
参数回调函数的作用域仅限于定义它们的路由器。它们不会被挂载的应用或路由器继承，也不会因从父路由器继承的路由参数而触发。因此，在 app 上定义的参数回调仅由 app 路由上定义的路由参数触发。

All param callbacks will be called before any handler of any route in which the param occurs, and they will each be called only once in a request-response cycle, even if the parameter is matched in multiple routes, as shown in the following examples.
所有参数回调都会在包含该参数的任意路由的任何处理程序之前被调用，并且在一个请求-响应周期中，每个回调仅会被调用一次，即使该参数在多个路由中匹配也是如此，如下例所示。

app.param('id', (req, res, next, id) => {
  console.log('CALLED ONLY ONCE')
  next()
})

app.get('/user/:id', (req, res, next) => {
  console.log('although this matches')
  next()
})

app.get('/user/:id', (req, res) => {
  console.log('and this matches too')
  res.end()
})

On GET /user/42, the following is printed:
在 GET /user/42 上，将打印以下内容：

CALLED ONLY ONCE
although this matches
and this matches too

app.param(['id', 'page'], (req, res, next, value) => {
  console.log('CALLED ONLY ONCE with', value)
  next()
})

app.get('/user/:id/:page', (req, res, next) => {
  console.log('although this matches')
  next()
})

app.get('/user/:id/:page', (req, res) => {
  console.log('and this matches too')
  res.end()
})

On GET /user/42/3, the following is printed:
在 GET /user/42/3 上，将打印以下内容：

CALLED ONLY ONCE with 42
CALLED ONLY ONCE with 3
although this matches
and this matches too

app.path()

Returns the canonical path of the app, a string.
返回应用的规范路径，一个字符串。

const app = express()
const blog = express()
const blogAdmin = express()

app.use('/blog', blog)
blog.use('/admin', blogAdmin)

console.log(app.path()) // ''
console.log(blog.path()) // '/blog'
console.log(blogAdmin.path()) // '/blog/admin'

The behavior of this method can become very complicated in complex cases of mounted apps: it is usually better to use req.baseUrl to get the canonical path of the app.
在挂载应用的复杂场景中，此方法的行为可能变得非常复杂：通常更推荐使用 req.baseUrl 来获取应用的标准路径。

app.post(path, callback [, callback ...])
app.post(路径, 回调函数 [, 回调函数 ...])

Routes HTTP POST requests to the specified path with the specified callback functions. For more information, see the routing guide.
将 HTTP POST 请求路由到指定路径，并执行相应的回调函数。更多信息，请参阅路由指南。

Arguments  参数

Example  示例

app.post('/', (req, res) => {
  res.send('POST request to homepage')
})

app.put(path, callback [, callback ...])

Routes HTTP PUT requests to the specified path with the specified callback functions.
将 HTTP PUT 请求路由到指定路径，并使用指定的回调函数处理。

Arguments  参数

Example  示例

app.put('/', (req, res) => {
  res.send('PUT request to homepage')
})

app.render(view, [locals], callback)
app.render(视图, [局部变量], 回调函数)

Returns the rendered HTML of a view via the callback function. It accepts an optional parameter that is an object containing local variables for the view. It is like res.render(), except it cannot send the rendered view to the client on its own.
通过 callback 函数返回视图渲染后的 HTML。它接受一个可选参数，该参数是一个包含视图局部变量的对象。类似于 res.render()，但它无法自行将渲染后的视图发送给客户端。

app.render('email', (err, html) => {
  // ...
})

app.render('email', { name: 'Tobi' }, (err, html) => {
  // ...
})

app.route(path)  app.route(路径)

Returns an instance of a single route, which you can then use to handle HTTP verbs with optional middleware. Use app.route() to avoid duplicate route names (and thus typo errors).
返回单个路由的实例，随后可用于通过可选中间件处理 HTTP 动词。使用 app.route() 以避免重复的路由名称（从而避免拼写错误）。

const app = express()

app.route('/events')
  .all((req, res, next) => {
    // runs for all HTTP verbs first
    // think of it as route specific middleware!
  })
  .get((req, res, next) => {
    res.json({})
  })
  .post((req, res, next) => {
    // maybe add a new event...
  })

app.set(name, value)  app.set(名称, 值)

Assigns setting name to value. You may store any value that you want, but certain names can be used to configure the behavior of the server. These special names are listed in the app settings table.
将设置 name 赋值为 value 。您可以存储任何所需的值，但某些名称可用于配置服务器的行为。这些特殊名称列在应用设置表中。

Calling app.set('foo', true) for a Boolean property is the same as calling app.enable('foo'). Similarly, calling app.set('foo', false) for a Boolean property is the same as calling app.disable('foo').
对布尔属性调用 app.set('foo', true) 等同于调用 app.enable('foo') 。类似地，对布尔属性调用 app.set('foo', false) 等同于调用 app.disable('foo') 。

Retrieve the value of a setting with app.get().
使用 app.get() 获取设置的值。

app.set('title', 'My Site')
app.get('title') // "My Site"

Application Settings  应用程序设置

The following table lists application settings.
下表列出了应用程序设置。

Note that sub-apps will:
请注意子应用将：

• Not inherit the value of settings that have a default value. You must set the value in the sub-app.
  不继承具有默认值的设置项值。必须在子应用中设置该值。
• Inherit the value of settings with no default value; these are explicitly noted in the table below.
  继承无默认值的设置项值；这些在下方表格中有明确标注。

Exceptions: Sub-apps will inherit the value of trust proxy even though it has a default value (for backward-compatibility); Sub-apps will not inherit the value of view cache in production (when NODE_ENV is “production”).
例外情况：子应用将继承 trust proxy 的值，尽管它有默认值（为了向后兼容）；在生产环境中（当 NODE_ENV 为“production”时），子应用不会继承 view cache 的值。

app.set('trust proxy', 'loopback')

app.set('trust proxy', 'loopback, 123.123.123.123')

app.set('trust proxy', 'loopback, linklocal, uniquelocal')

app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal'])

app.set('trust proxy', (ip) => {
  if (ip === '127.0.0.1' || ip === '123.123.123.123') return true // trusted IPs
  else return false
})

app.set('etag', (body, encoding) => {
  return generateHash(body, encoding) // consider the function is defined
})

app.use([path,] callback [, callback...])
app.use([路径,] 回调函数 [, 回调函数...])

Mounts the specified middleware function or functions at the specified path: the middleware function is executed when the base of the requested path matches path.
将指定的中间件函数或函数组挂载到指定路径：当请求路径的基址匹配 path 时，执行该中间件函数。

Arguments  参数

Description  描述

A route will match any path that follows its path immediately with a “/”. For example: app.use('/apple', ...) will match “/apple”, “/apple/images”, “/apple/images/news”, and so on.
一个路由会匹配任何紧随其路径后带有“ / ”的路径。例如： app.use('/apple', ...) 将匹配“/apple”、“/apple/images”、“/apple/images/news”等。

Since path defaults to “/”, middleware mounted without a path will be executed for every request to the app. For example, this middleware function will be executed for every request to the app:
由于 path 默认为“/”，未指定路径挂载的中间件将对应用的每个请求执行。例如，以下中间件函数将对应用的每个请求执行：

app.use((req, res, next) => {
  console.log('Time: %d', Date.now())
  next()
})

Middleware functions are executed sequentially, therefore the order of middleware inclusion is important.
中间件函数按顺序执行，因此中间件的包含顺序很重要。

// this middleware will not allow the request to go beyond it
app.use((req, res, next) => {
  res.send('Hello World')
})

// requests will never reach this route
app.get('/', (req, res) => {
  res.send('Welcome')
})

Error-handling middleware
错误处理中间件

Error-handling middleware always takes four arguments. You must provide four arguments to identify it as an error-handling middleware function. Even if you don’t need to use the next object, you must specify it to maintain the signature. Otherwise, the next object will be interpreted as regular middleware and will fail to handle errors. For details about error-handling middleware, see: Error handling.
错误处理中间件始终需要四个参数。必须提供四个参数以将其识别为错误处理中间件函数。即使不需要使用 next 对象，也必须指定它以保持签名一致。否则， next 对象将被解释为常规中间件，从而无法处理错误。有关错误处理中间件的详细信息，请参阅：错误处理。

Define error-handling middleware functions in the same way as other middleware functions, except with four arguments instead of three, specifically with the signature (err, req, res, next)):
定义错误处理中间件函数的方式与其他中间件函数相同，但需使用四个参数而非三个，具体签名为 (err, req, res, next) )：

app.use((err, req, res, next) => {
  console.error(err.stack)
  res.status(500).send('Something broke!')
})

Path examples  路径示例

The following table provides some simple examples of valid path values for mounting middleware.
下表提供了一些有效的 path 值用于挂载中间件的简单示例。

app.use('/abcd', (req, res, next) => {
  next()
})

app.use('/ab{c}d', (req, res, next) => {
  next()
})

app.use(/\/abc|\/xyz/, (req, res, next) => {
  next()
})

app.use(['/abcd', '/xyza', /\/lmn|\/pqr/], (req, res, next) => {
  next()
})

Middleware callback function examples
中间件回调函数示例

The following table provides some simple examples of middleware functions that can be used as the callback argument to app.use(), app.METHOD(), and app.all().
下表提供了一些简单的中间件函数示例，这些函数可用作 callback 参数传递给 app.use() 、 app.METHOD() 和 app.all() 。

app.use((req, res, next) => {
  next()
})

const router = express.Router()
router.get('/', (req, res, next) => {
  next()
})
app.use(router)

const subApp = express()
subApp.get('/', (req, res, next) => {
  next()
})
app.use(subApp)

const r1 = express.Router()
r1.get('/', (req, res, next) => {
  next()
})

const r2 = express.Router()
r2.get('/', (req, res, next) => {
  next()
})

app.use(r1, r2)

const r1 = express.Router()
r1.get('/', (req, res, next) => {
  next()
})

const r2 = express.Router()
r2.get('/', (req, res, next) => {
  next()
})

app.use([r1, r2])

function mw1 (req, res, next) { next() }
function mw2 (req, res, next) { next() }

const r1 = express.Router()
r1.get('/', (req, res, next) => { next() })

const r2 = express.Router()
r2.get('/', (req, res, next) => { next() })

const subApp = express()
subApp.get('/', (req, res, next) => { next() })

app.use(mw1, [mw2, r1, r2], subApp)

Following are some examples of using the express.static middleware in an Express app.

Serve static content for the app from the “public” directory in the application directory:

// GET /style.css etc
app.use(express.static(path.join(__dirname, 'public')))

Mount the middleware at “/static” to serve static content only when their request path is prefixed with “/static”:

// GET /static/style.css etc.
app.use('/static', express.static(path.join(__dirname, 'public')))

Disable logging for static content requests by loading the logger middleware after the static middleware:

app.use(express.static(path.join(__dirname, 'public')))
app.use(logger())

Serve static files from multiple directories, but give precedence to “./public” over the others:

app.use(express.static(path.join(__dirname, 'public')))
app.use(express.static(path.join(__dirname, 'files')))
app.use(express.static(path.join(__dirname, 'uploads')))

req.app

This property holds a reference to the instance of the Express application that is using the middleware.

If you follow the pattern in which you create a module that just exports a middleware function and require() it in your main file, then the middleware can access the Express instance via req.app

For example:

// index.js
app.get('/viewdirectory', require('./mymiddleware.js'))

// mymiddleware.js
module.exports = (req, res) => {
  res.send(`The views directory is ${req.app.get('views')}`)
}

req.baseUrl

The URL path on which a router instance was mounted.

The req.baseUrl property is similar to the mountpath property of the app object, except app.mountpath returns the matched path pattern(s).

For example:

const greet = express.Router()

greet.get('/jp', (req, res) => {
  console.log(req.baseUrl) // /greet
  res.send('Konichiwa!')
})

app.use('/greet', greet) // load the router on '/greet'

Even if you use a path pattern or a set of path patterns to load the router, the baseUrl property returns the matched string, not the pattern(s). In the following example, the greet router is loaded on two path patterns.

app.use(['/gre:"param"t', '/hel{l}o'], greet) // load the router on '/gre:"param"t' and '/hel{l}o'

When a request is made to /greet/jp, req.baseUrl is “/greet”. When a request is made to /hello/jp, req.baseUrl is “/hello”.

req.body

Contains key-value pairs of data submitted in the request body. By default, it is undefined, and is populated when you use body-parsing middleware such as express.json() or express.urlencoded().

The following example shows how to use body-parsing middleware to populate req.body.

const express = require('express')

const app = express()

app.use(express.json()) // for parsing application/json
app.use(express.urlencoded({ extended: true })) // for parsing application/x-www-form-urlencoded

app.post('/profile', (req, res, next) => {
  console.log(req.body)
  res.json(req.body)
})

req.cookies

When using cookie-parser middleware, this property is an object that contains cookies sent by the request. If the request contains no cookies, it defaults to {}.

// Cookie: name=tj
console.dir(req.cookies.name)
// => "tj"

If the cookie has been signed, you have to use req.signedCookies.

For more information, issues, or concerns, see cookie-parser.

req.fresh

When the response is still “fresh” in the client’s cache true is returned, otherwise false is returned to indicate that the client cache is now stale and the full response should be sent.

When a client sends the Cache-Control: no-cache request header to indicate an end-to-end reload request, this module will return false to make handling these requests transparent.

Further details for how cache validation works can be found in the HTTP/1.1 Caching Specification.

console.dir(req.fresh)
// => true

req.host

Contains the host derived from the Host HTTP header.

When the trust proxy setting does not evaluate to false, this property will instead get the value from the X-Forwarded-Host header field. This header can be set by the client or by the proxy.

If there is more than one X-Forwarded-Host header in the request, the value of the first header is used. This includes a single header with comma-separated values, in which the first value is used.

// Host: "example.com:3000"
console.dir(req.host)
// => 'example.com:3000'

// Host: "[::1]:3000"
console.dir(req.host)
// => '[::1]:3000'

req.hostname

Contains the hostname derived from the Host HTTP header.

When the trust proxy setting does not evaluate to false, this property will instead get the value from the X-Forwarded-Host header field. This header can be set by the client or by the proxy.

If there is more than one X-Forwarded-Host header in the request, the value of the first header is used. This includes a single header with comma-separated values, in which the first value is used.

// Host: "example.com:3000"
console.dir(req.hostname)
// => 'example.com'

req.ip

Contains the remote IP address of the request.

When the trust proxy setting does not evaluate to false, the value of this property is derived from the left-most entry in the X-Forwarded-For header. This header can be set by the client or by the proxy.

console.dir(req.ip)
// => "127.0.0.1"

req.ips

When the trust proxy setting does not evaluate to false, this property contains an array of IP addresses specified in the X-Forwarded-For request header. Otherwise, it contains an empty array. This header can be set by the client or by the proxy.

For example, if X-Forwarded-For is client, proxy1, proxy2, req.ips would be ["client", "proxy1", "proxy2"], where proxy2 is the furthest downstream.

req.method

Contains a string corresponding to the HTTP method of the request: GET, POST, PUT, and so on.

req.originalUrl

This property is much like req.url; however, it retains the original request URL, allowing you to rewrite req.url freely for internal routing purposes. For example, the “mounting” feature of app.use() will rewrite req.url to strip the mount point.

// GET /search?q=something
console.dir(req.originalUrl)
// => "/search?q=something"

req.originalUrl is available both in middleware and router objects, and is a combination of req.baseUrl and req.url. Consider following example:

// GET 'http://www.example.com/admin/new?sort=desc'
app.use('/admin', (req, res, next) => {
  console.dir(req.originalUrl) // '/admin/new?sort=desc'
  console.dir(req.baseUrl) // '/admin'
  console.dir(req.path) // '/new'
  next()
})

req.params

This property is an object containing properties mapped to the named route “parameters”. For example, if you have the route /user/:name, then the “name” property is available as req.params.name. This object defaults to {}.

// GET /user/tj
console.dir(req.params.name)
// => "tj"

When you use a regular expression for the route definition, capture groups are provided in the array using req.params[n], where n is the n^th capture group.

app.use(/^\/file\/(.*)$/, (req, res) => {
  // GET /file/javascripts/jquery.js
  console.dir(req.params[0])
  // => "javascripts/jquery.js"
})

If you need to make changes to a key in req.params, use the app.param handler. Changes are applicable only to parameters already defined in the route path.

Any changes made to the req.params object in a middleware or route handler will be reset.

req.path

Contains the path part of the request URL.

// example.com/users?sort=desc
console.dir(req.path)
// => "/users"

req.protocol

Contains the request protocol string: either http or (for TLS requests) https.

When the trust proxy setting does not evaluate to false, this property will use the value of the X-Forwarded-Proto header field if present. This header can be set by the client or by the proxy.

console.dir(req.protocol)
// => "http"

req.query

This property is an object containing a property for each query string parameter in the route. When query parser is set to disabled, it is an empty object {}, otherwise it is the result of the configured query parser.

The value of this property can be configured with the query parser application setting to work how your application needs it. A very popular query string parser is the qs module, and this is used by default. The qs module is very configurable with many settings, and it may be desirable to use different settings than the default to populate req.query:

const qs = require('qs')
app.set('query parser',
  (str) => qs.parse(str, { /* custom options */ }))

Check out the query parser application setting documentation for other customization options.

req.res

This property holds a reference to the response object that relates to this request object.

req.route

Contains the currently-matched route, a string. For example:

app.get('/user/{:id}', (req, res) => {
  console.dir(req.route, { depth: null })
  res.send('GET')
})

Example output from the previous snippet:

Route {
  path: '/user/{:id}',
  stack: [
    Layer {
      handle: [Function (anonymous)],
      keys: [],
      name: '<anonymous>',
      params: undefined,
      path: undefined,
      slash: false,
      matchers: [ [Function: match] ],
      method: 'get'
    }
  ],
  methods: [Object: null prototype] { get: true }
}

req.secure

A Boolean property that is true if a TLS connection is established. Equivalent to the following:

req.protocol === 'https'

req.signedCookies

When using cookie-parser middleware, this property contains signed cookies sent by the request, unsigned and ready for use. Signed cookies reside in a different object to show developer intent; otherwise, a malicious attack could be placed on req.cookie values (which are easy to spoof). Note that signing a cookie does not make it “hidden” or encrypted; but simply prevents tampering (because the secret used to sign is private).

If no signed cookies are sent, the property defaults to {}.

// Cookie: user=tobi.CP7AWaXDfAKIRfH49dQzKJx7sKzzSoPq7/AcBBRVwlI3
console.dir(req.signedCookies.user)
// => "tobi"

For more information, issues, or concerns, see cookie-parser.

req.stale

Indicates whether the request is “stale,” and is the opposite of req.fresh. For more information, see req.fresh.

console.dir(req.stale)
// => true

req.subdomains

An array of subdomains in the domain name of the request.

// Host: "tobi.ferrets.example.com"
console.dir(req.subdomains)
// => ["ferrets", "tobi"]

The application property subdomain offset, which defaults to 2, is used for determining the beginning of the subdomain segments. To change this behavior, change its value using app.set.

req.xhr

A Boolean property that is true if the request’s X-Requested-With header field is “XMLHttpRequest”, indicating that the request was issued by a client library such as jQuery.

console.dir(req.xhr)
// => true

req.accepts(types)

Checks if the specified content types are acceptable, based on the request’s Accept HTTP header field. The method returns the best match, or if none of the specified content types is acceptable, returns false (in which case, the application should respond with 406 "Not Acceptable").

The type value may be a single MIME type string (such as “application/json”), an extension name such as “json”, a comma-delimited list, or an array. For a list or array, the method returns the best match (if any).

// Accept: text/html
req.accepts('html')
// => "html"

// Accept: text/*, application/json
req.accepts('html')
// => "html"
req.accepts('text/html')
// => "text/html"
req.accepts(['json', 'text'])
// => "json"
req.accepts('application/json')
// => "application/json"

// Accept: text/*, application/json
req.accepts('image/png')
req.accepts('png')
// => false

// Accept: text/*;q=.5, application/json
req.accepts(['html', 'json'])
// => "json"

For more information, or if you have issues or concerns, see accepts.

req.acceptsCharsets(charset [, ...])

Returns the first accepted charset of the specified character sets, based on the request’s Accept-Charset HTTP header field. If none of the specified charsets is accepted, returns false.

For more information, or if you have issues or concerns, see accepts.

req.acceptsEncodings(encoding [, ...])

Returns the first accepted encoding of the specified encodings, based on the request’s Accept-Encoding HTTP header field. If none of the specified encodings is accepted, returns false.

For more information, or if you have issues or concerns, see accepts.

req.acceptsLanguages([lang, ...])

Returns the first accepted language of the specified languages, based on the request’s Accept-Language HTTP header field. If none of the specified languages is accepted, returns false.

If no lang argument is given, then req.acceptsLanguages() returns all languages from the HTTP Accept-Language header as an Array.

For more information, or if you have issues or concerns, see accepts.

Express (5.x) source: request.js line 172

Accepts (2.0) source: index.js line 195

req.get(field)

Returns the specified HTTP request header field (case-insensitive match). The Referrer and Referer fields are interchangeable.

req.get('Content-Type')
// => "text/plain"

req.get('content-type')
// => "text/plain"

req.get('Something')
// => undefined

Aliased as req.header(field).

req.is(type)

Returns the matching content type if the incoming request’s “Content-Type” HTTP header field matches the MIME type specified by the type parameter. If the request has no body, returns null. Returns false otherwise.

// With Content-Type: text/html; charset=utf-8
req.is('html') // => 'html'
req.is('text/html') // => 'text/html'
req.is('text/*') // => 'text/*'

// When Content-Type is application/json
req.is('json') // => 'json'
req.is('application/json') // => 'application/json'
req.is('application/*') // => 'application/*'

req.is('html')
// => false

For more information, or if you have issues or concerns, see type-is.

req.range(size[, options])

Range header parser.

The size parameter is the maximum size of the resource.

The options parameter is an object that can have the following properties.

An array of ranges will be returned or negative numbers indicating an error parsing.

• -2 signals a malformed header string
• -1 signals an unsatisfiable range

// parse header from request
const range = req.range(1000)

// the type of the range
if (range.type === 'bytes') {
  // the ranges
  range.forEach((r) => {
    // do something with r.start and r.end
  })
}

res.app

This property holds a reference to the instance of the Express application that is using the middleware.

res.app is identical to the req.app property in the request object.

res.headersSent

Boolean property that indicates if the app sent HTTP headers for the response.

app.get('/', (req, res) => {
  console.log(res.headersSent) // false
  res.send('OK')
  console.log(res.headersSent) // true
})

res.locals

Use this property to set variables accessible in templates rendered with res.render. The variables set on res.locals are available within a single request-response cycle, and will not be shared between requests.

In order to keep local variables for use in template rendering between requests, use app.locals instead.

This property is useful for exposing request-level information such as the request path name, authenticated user, user settings, and so on to templates rendered within the application.

app.use((req, res, next) => {
  // Make `user` and `authenticated` available in templates
  res.locals.user = req.user
  res.locals.authenticated = !req.user.anonymous
  next()
})

res.req

This property holds a reference to the request object that relates to this response object.

res.append(field [, value])

Appends the specified value to the HTTP response header field. If the header is not already set, it creates the header with the specified value. The value parameter can be a string or an array.

res.append('Link', ['<http://localhost/>', '<http://localhost:3000/>'])
res.append('Set-Cookie', 'foo=bar; Path=/; HttpOnly')
res.append('Warning', '199 Miscellaneous warning')

res.attachment([filename])

Sets the HTTP response Content-Disposition header field to “attachment”. If a filename is given, then it sets the Content-Type based on the extension name via res.type(), and sets the Content-Disposition “filename=” parameter.

res.attachment()
// Content-Disposition: attachment

res.attachment('path/to/logo.png')
// Content-Disposition: attachment; filename="logo.png"
// Content-Type: image/png

res.cookie(name, value [, options])

Sets cookie name to value. The value parameter may be a string or object converted to JSON.

The options parameter is an object that can have the following properties.