5.x API

express.json([options])

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

Returns middleware that only parses JSON and only looks at requests where the Content-Type header matches the type option. 返回仅解析JSON并仅查看Content-Type标头与类型选项匹配的请求的中间件。This parser accepts any Unicode encoding of the body and supports automatic inflation of gzip and deflate encodings.此解析器接受正文的任何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 an empty object ({}) if there was no body to parse, the Content-Type was not matched, or an error occurred.在中间件（即req.body）之后的request对象上填充包含已解析数据的新body对象，如果没有要解析的body、Content-Type不匹配或发生错误，则填充空对象（{}）。

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

express.static(root, [options])

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

The root argument specifies the root directory from which to serve static assets. root参数指定为静态资产提供服务的根目录。The function determines the file to serve by combining req.url with the provided root directory. 该函数通过将req.url与提供的根目录相结合来确定要服务的文件。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.当找不到文件时，它不会发送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. 有关详细信息，请参阅在Express中提供静态文件。and Using middleware - Built-in middleware.以及使用中间件-内置中间件。

dotfiles

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

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

NOTE: With the default value, it will not ignore files in a directory that begins with a dot.：使用默认值，它不会忽略以点开头的目录中的文件。

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. 如果此选项为true，则客户端错误（如错误请求或对不存在的文件的请求）将导致此中间件仅调用next()来调用堆栈中的下一个中间件。When false, these errors (even 404s), will invoke next(err).如果为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，以便可以将多个物理目录映射到同一web地址，或用于填充不存在文件的路由。

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. 如果您已将此中间件安装在严格设计为单个文件系统目录的路径上，则使用false，这允许短路404以减少开销。This middleware will also reply to all methods.该中间件还将响应所有方法。

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.，响应对象。
• path, the file path that is being sent.，正在发送的文件路径。
• stat, the stat object of the file that is being sent.，正在发送的文件的stat对象。

Example of express.staticexpress.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: function (res, path, stat) {
    res.set('x-timestamp', Date.now())
  }
}

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

express.Router([options])

Creates a new router object.创建一个新的Router对象。

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.您可以像应用程序一样向路由器添加中间件和HTTP方法路由（如get、put、post等）。

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

express.urlencoded([options])

This is a built-in middleware function in Express. 这是Express中的内置中间件函数。It parses incoming requests with urlencoded payloads and is based on body-parser.它使用URL编码的有效负载解析传入请求，并基于主体解析器。

Returns middleware that only parses urlencoded bodies and only looks at requests where the Content-Type header matches the type option. 返回中间件，该中间件仅解析URL编码的实体，并仅查看Content-Type标头与类型选项匹配的请求。This parser accepts only UTF-8 encoding of the body and supports automatic inflation of gzip and deflate encodings.该解析器只接受主体的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 an empty object ({}) if there was no body to parse, the Content-Type was not matched, or an error occurred. 在中间件（即req.body）之后的request对象上填充包含已解析数据的新body对象，如果没有要解析的body、Content-Type不匹配或发生错误，则填充空对象（{}）。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).此对象将包含键值对，其中值可以是字符串或数组（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.app.locals对象的属性是应用程序中的局部变量。

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('/', function (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('/', function (req, res) {
  console.log(admin.mountpath) // [ '/adm*n', '/manager' ]
  res.send('Admin Homepage')
})

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

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

app.router

The application’s in-built instance of router. 应用程序的内置路由器实例。This is created lazily, on first access.这是在第一次访问时惰性地创建的。

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

router.get('/', function (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. mount事件在子应用程序上启动，当它挂载在父应用程序上时。The parent app is passed to the callback function.父应用程序被传递给回调函数。

const admin = express()

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

admin.get('/', function (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', function (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. app.all()方法用于映射特定路径前缀或任意匹配的“全局”逻辑。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.请记住，这些回调不必充当端点：loadUser可以执行一项任务，然后调用next()继续匹配后续路由。

app.all('*', requireAuthentication, loadUser)

Or the equivalent:或同等标准：

app.all('*', requireAuthentication)
app.all('*', 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/*', requireAuthentication)

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

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

Arguments参数

Example实例

app.delete('/', function (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. 将布尔设置name设置为false，其中name是app设置中的属性之一。Calling app.set('foo', false) for a Boolean property is the same as calling app.disable('foo').为布尔属性调用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，其中名称是应用程序设置表中的属性之一。

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. 将布尔设置name设置为true，其中name是app设置表中的属性之一。Calling app.set('foo', true) for a Boolean property is the same as calling app.enable('foo').为布尔属性调用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，其中名称是app设置表中的属性之一。

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. 默认情况下，Express将基于文件扩展名require()引擎。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.例如，如果试图呈现“foopug”文件，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提供了一个.renderFile()方法，其签名与Express所期望的相同：(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库将节点模板引擎映射为遵循此约定，因此它们可以与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. 返回name app设置的值，其中name是app设置表中的字符串之一。For example:例如：

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('/', function (req, res) {
  res.send('GET request to homepage')
})

app.listen(path, [callback])

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

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

app.listen([port[, host[, backlog]]][, callback])

Binds and listens for connections on the specified host and port. 绑定并侦听指定主机和端口上的连接。This method is identical to Node’s http.Server.listen().此方法与节点的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. express()返回的app实际上是一个JavaScriptFunction，旨在作为回调传递给节点的HTTP服务器，以处理请求。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):这使得为应用程序的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 () {
  var server = http.createServer(this)
  return server.listen.apply(server, arguments)
}

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

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

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(). API文档中只有最流行的HTTP方法app.get()、app.post()、app.put()和app.delete()的显式条目。However, the other methods listed above work in exactly the same way.然而，上面列出的其他方法的工作方式完全相同。

To route methods that translate to invalid JavaScript variable names, use the bracket notation. 要路由转换为无效JavaScript变量名的方法，请使用括号表示法。For example, app['m-search']('/', function ....例如，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. app.all()方法不是从任何HTTP方法派生的，而是在所有HTTP请求方法的指定路径上加载中间件。For more information, see app.all.有关更多信息，请参阅app.all。

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

app.param(name, callback)

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. 向路由参数添加回调触发器，其中name是参数的名称或它们的数组，callback是回调函数。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.回调函数的参数依次为请求对象、响应对象、下一个中间件、参数值和参数名称。

If name is an array, the callback trigger is registered for each parameter declared in it, in the order in which they are declared. 如果name是一个数组，则按照声明的顺序为其中声明的每个参数注册callback触发器。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. 此外，对于除最后一个之外的每个已声明参数，在回调中调用next将调用下一个已声明参数的回调。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.对于最后一个参数，调用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', function (req, res, next, id) {
  // try to get the user details from the User model and attach it to the request object
  User.find(id, function (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. Param回调函数是定义它们的路由器的本地函数。They are not inherited by mounted apps or 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.所有param回调都将在任何路由的任何处理程序之前被调用，在一个请求-响应周期中，每个回调都只被调用一次，即使参数在多个路由中匹配，如以下示例所示。

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

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

app.get('/user/:id', function (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'], function (req, res, next, value) {
  console.log('CALLED ONLY ONCE with', value)
  next()
})

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

app.get('/user/:id/:page', function (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 ...])

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

Arguments参数

Example示例

app.post('/', function (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('/', function (req, res) {
  res.send('PUT request to homepage')
})

app.render(view, [locals], callback)

Returns the rendered HTML of a view via the callback function. 通过callback函数返回视图的呈现HTML。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.

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

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

app.route(path)

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).

const app = express()

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

app.set(name, value)

Assigns setting name to value. 将设置name指定给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.这些特殊名称列在app设置表中。

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').

Retrieve the value of a setting with 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”).

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', function (ip) {
  if (ip === '127.0.0.1' || ip === '123.123.123.123') return true // trusted IPs
  else return false
})

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

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

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.

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.

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:

app.use(function (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(function (req, res, next) {
  res.send('Hello World')
})

// requests will never reach this route
app.get('/', function (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.

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(function (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', function (req, res, next) {
  next()
})

app.use('/abc?d', function (req, res, next) {
  next()
})

app.use('/ab+cd', function (req, res, next) {
  next()
})

app.use('/ab*cd', function (req, res, next) {
  next()
})

app.use('/a(bc)?d', function (req, res, next) {
  next()
})

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

app.use(['/abcd', '/xyza', /\/lmn|\/pqr/], function (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(). Even though the examples are for app.use(), they are also valid for app.use(), app.METHOD(), and app.all().

app.use(function (req, res, next) {
  next()
})

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

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

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

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

app.use(r1, r2)

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

const r2 = express.Router()
r2.get('/', function (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('/', function (req, res, next) { next() })

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

const subApp = express()
subApp.get('/', function (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 = function (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', function (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+t', '/hel{2}o'], greet) // load the router on '/gre+t' and '/hel{2}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 body-parser and multer.

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

const app = require('express')()
const bodyParser = require('body-parser')
const multer = require('multer') // v1.0.5
const upload = multer() // for parsing multipart/form-data

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

app.post('/profile', upload.array(), function (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', function (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. This rule is applied to unnamed wild card matches with string routes such as /file/*:

// 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.

req.route

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

app.get('/user/:id?', function userIdHandler (req, res) {
  console.log(req.route)
  res.send('GET')
})

Example output from the previous snippet:

{ path: '/user/:id?',
  stack:
   [ { handle: [Function: userIdHandler],
       name: 'userIdHandler',
       params: undefined,
       path: undefined,
       keys: [],
       regexp: /^\/?$/i,
       method: 'get' } ],
  methods: { 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.

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

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(function (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('/', function (req, res) {
  console.log(res.headersSent) // false
  res.send('OK')
  console.log(res.headersSent) // true
})

res.locals

An object that contains response local variables scoped to the request, and therefore available only to the view(s) rendered during that request / response cycle (if any). Otherwise, this property is identical to app.locals.

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

app.use(function (req, res, next) {
  res.locals.user = req.user
  res.locals.authenticated = !req.user.anonymous
  next()
})

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.

Note: calling res.set() after res.append() will reset the previously-set header value.

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.

For example:

res.cookie('name', 'tobi', { domain: '.example.com', path: '/admin', secure: true })
res.cookie('rememberme', '1', { expires: new Date(Date.now() + 900000), httpOnly: true })

The encode option allows you to choose the function used for cookie value encoding. Does not support asynchronous functions.

Example use case: You need to set a domain-wide cookie for another site in your organization. This other site (not under your administrative control) does not use URI-encoded cookie values.

// Default encoding
res.cookie('some_cross_domain_cookie', 'http://mysubdomain.example.com', { domain: 'example.com' })
// Result: 'some_cross_domain_cookie=http%3A%2F%2Fmysubdomain.example.com; Domain=example.com; Path=/'

// Custom encoding
res.cookie('some_cross_domain_cookie', 'http://mysubdomain.example.com', { domain: 'example.com', encode: String })
// Result: 'some_cross_domain_cookie=http://mysubdomain.example.com; Domain=example.com; Path=/;'

The maxAge option is a convenience option for setting “expires” relative to the current time in milliseconds. The following is equivalent to the second example above.

res.cookie('rememberme', '1', { maxAge: 900000, httpOnly: true })

You can pass an object as the value parameter; it is then serialized as JSON and parsed by bodyParser() middleware.

res.cookie('cart', { items: [1, 2, 3] })
res.cookie('cart', { items: [1, 2, 3] }, { maxAge: 900000 })

When using cookie-parser middleware, this method also supports signed cookies. Simply include the signed option set to true. Then res.cookie() will use the secret passed to cookieParser(secret) to sign the value.

res.cookie('name', 'tobi', { signed: true })

Later you may access this value through the req.signedCookies object.

res.clearCookie(name [, options])

Clears the cookie specified by name. For details about the options object, see res.cookie().

res.cookie('name', 'tobi', { path: '/admin' })
res.clearCookie('name', { path: '/admin' })

res.download(path [, filename] [, options] [, fn])

Transfers the file at path as an “attachment”. Typically, browsers will prompt the user for download. By default, the Content-Disposition header “filename=” parameter is path (this typically appears in the browser dialog). Override this default with the filename parameter.

When an error occurs or transfer is complete, the method calls the optional callback function fn. This method uses res.sendFile() to transfer the file.

The optional options argument passes through to the underlying res.sendFile() call, and takes the exact same parameters.

res.download('/report-12345.pdf')

res.download('/report-12345.pdf', 'report.pdf')

res.download('/report-12345.pdf', 'report.pdf', function (err) {
  if (err) {
    // Handle error, but keep in mind the response may be partially-sent
    // so check res.headersSent
  } else {
    // decrement a download credit, etc.
  }
})

res.end([data] [, encoding])

Ends the response process. 结束响应过程。This method actually comes from Node core, specifically the response.end() method of http.ServerResponse.这个方法实际上来自节点核心，特别是http.ServerResponse的response.end()方法。

Use to quickly end the response without any data. 用于在没有任何数据的情况下快速结束响应。If you need to respond with data, instead use methods such as res.send() and res.json().如果需要使用数据进行响应，请改用res.send()和res.json()等方法。

res.end()
res.status(404).end()

res.format(object)

Performs content-negotiation on the Accept HTTP header on the request object, when present. 在请求对象的Accept HTTP头上执行内容协商（如果存在）。It uses req.accepts() to select a handler for the request, based on the acceptable types ordered by their quality values. 它使用req.accepts()根据可接受类型的质量值排序，为请求选择一个处理程序。If the header is not specified, the first callback is invoked. 如果未指定标头，将调用第一个回调。When no match is found, the server responds with 406 “Not Acceptable”, or invokes the default callback.当找不到匹配项时，服务器以406“不可接受”响应，或调用default回调。

The Content-Type response header is set when a callback is selected. 选择回调时，将设置Content-Type响应标头。However, you may alter this within the callback using methods such as res.set() or res.type().但是，您可以在回调中使用诸如res.set()或res.type()之类的方法来更改它。

The following example would respond with { "message": "hey" } when the Accept header field is set to “application/json” or “*/json” (however if it is “*/*”, then the response will be “hey”).下面的示例当Accept 标头字段设置为“application/json”或“*/json”时将以{ "message": "hey" }响应（但是，如果它是“*/*”，那么响应将是“hey”）。

res.format({
  'text/plain': function () {
    res.send('hey')
  },

  'text/html': function () {
    res.send('<p>hey</p>')
  },

  'application/json': function () {
    res.send({ message: 'hey' })
  },

  default: function () {
    // log the request and respond with 406
    res.status(406).send('Not Acceptable')
  }
})

In addition to canonicalized MIME types, you may also use extension names mapped to these types for a slightly less verbose implementation:

res.format({
  text: function () {
    res.send('hey')
  },

  html: function () {
    res.send('<p>hey</p>')
  },

  json: function () {
    res.send({ message: 'hey' })
  }
})

res.get(field)

Returns the HTTP response header specified by field. The match is case-insensitive.

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

res.json([body])

Sends a JSON response. This method sends a response (with the correct content-type) that is the parameter converted to a JSON string using JSON.stringify().

The parameter can be any JSON type, including object, array, string, Boolean, number, or null, and you can also use it to convert other values to JSON.

res.json(null)
res.json({ user: 'tobi' })
res.status(500).json({ error: 'message' })

res.jsonp([body])

Sends a JSON response with JSONP support. This method is identical to res.json(), except that it opts-in to JSONP callback support.

res.jsonp(null)
// => callback(null)

res.jsonp({ user: 'tobi' })
// => callback({ "user": "tobi" })

res.status(500).jsonp({ error: 'message' })
// => callback({ "error": "message" })

By default, the JSONP callback name is simply callback. Override this with the jsonp callback name setting.

The following are some examples of JSONP responses using the same code:

// ?callback=foo
res.jsonp({ user: 'tobi' })
// => foo({ "user": "tobi" })

app.set('jsonp callback name', 'cb')

// ?cb=foo
res.status(500).jsonp({ error: 'message' })
// => foo({ "error": "message" })

res.links(links)

Joins the links provided as properties of the parameter to populate the response’s Link HTTP header field.

For example, the following call:

res.links({
  next: 'http://api.example.com/users?page=2',
  last: 'http://api.example.com/users?page=5'
})

Yields the following results:

Link: <http://api.example.com/users?page=2>; rel="next",
      <http://api.example.com/users?page=5>; rel="last"

res.location(path)

Sets the response Location HTTP header to the specified path parameter.

res.location('/foo/bar')
res.location('http://example.com')
res.location('back')

A path value of “back” has a special meaning, it refers to the URL specified in the Referer header of the request. If the Referer header was not specified, it refers to “/”.

res.redirect([status,] path)

Redirects to the URL derived from the specified path, with specified status, a positive integer that corresponds to an HTTP status code . If not specified, status defaults to “302 “Found”.

res.redirect('/foo/bar')
res.redirect('http://example.com')
res.redirect(301, 'http://example.com')
res.redirect('../login')

Redirects can be a fully-qualified URL for redirecting to a different site:

res.redirect('http://google.com')

Redirects can be relative to the root of the host name. For example, if the application is on http://example.com/admin/post/new, the following would redirect to the URL http://example.com/admin:

res.redirect('/admin')

Redirects can be relative to the current URL. For example, from http://example.com/blog/admin/ (notice the trailing slash), the following would redirect to the URL http://example.com/blog/admin/post/new.

res.redirect('post/new')

Redirecting to post/new from http://example.com/blog/admin (no trailing slash), will redirect to http://example.com/blog/post/new.

If you found the above behavior confusing, think of path segments as directories (with trailing slashes) and files, it will start to make sense.

Path-relative redirects are also possible. If you were on http://example.com/admin/post/new, the following would redirect to http://example.com/admin/post:

res.redirect('..')

A back redirection redirects the request back to the referer, defaulting to / when the referer is missing.

res.redirect('back')

res.render(view [, locals] [, callback])

Renders a view and sends the rendered HTML string to the client. Optional parameters:

• locals, an object whose properties define local variables for the view.
• callback, a callback function. If provided, the method returns both the possible error and rendered string, but does not perform an automated response. When an error occurs, the method invokes next(err) internally.

The view argument is a string that is the file path of the view file to render. This can be an absolute path, or a path relative to the views setting. If the path does not contain a file extension, then the view engine setting determines the file extension. If the path does contain a file extension, then Express will load the module for the specified template engine (via require()) and render it using the loaded module’s __express function.

For more information, see Using template engines with Express.

NOTE: The view argument performs file system operations like reading a file from disk and evaluating Node.js modules, and as so for security reasons should not contain input from the end-user.

// send the rendered view to the client
res.render('index')

// if a callback is specified, the rendered HTML string has to be sent explicitly
res.render('index', function (err, html) {
  res.send(html)
})

// pass a local variable to the view
res.render('user', { name: 'Tobi' }, function (err, html) {
  // ...
})

res.send([body])

Sends the HTTP response.

The body parameter can be a Buffer object, a String, an object, Boolean, or an Array. For example:

res.send(Buffer.from('whoop'))
res.send({ some: 'json' })
res.send('<p>some html</p>')
res.status(404).send('Sorry, we cannot find that!')
res.status(500).send({ error: 'something blew up' })

This method performs many useful tasks for simple non-streaming responses: For example, it automatically assigns the Content-Length HTTP response header field (unless previously defined) and provides automatic HEAD and HTTP cache freshness support.

When the parameter is a Buffer object, the method sets the Content-Type response header field to “application/octet-stream”, unless previously defined as shown below:

res.set('Content-Type', 'text/html')
res.send(Buffer.from('<p>some html</p>'))

When the parameter is a String, the method sets the Content-Type to “text/html”:

res.send('<p>some html</p>')

When the parameter is an Array or Object, Express responds with the JSON representation:

res.send({ user: 'tobi' })
res.send([1, 2, 3])

res.sendFile(path [, options] [, fn])

Transfers the file at the given path. Sets the Content-Type response HTTP header field based on the filename’s extension. Unless the root option is set in the options object, path must be an absolute path to the file.

The following table provides details on the options parameter.

The method invokes the callback function fn(err) when the transfer is complete or when an error occurs. If the callback function is specified and an error occurs, the callback function must explicitly handle the response process either by ending the request-response cycle, or by passing control to the next route.

Here is an example of using res.sendFile with all its arguments.

app.get('/file/:name', function (req, res, next) {
  const options = {
    root: path.join(__dirname, 'public'),
    dotfiles: 'deny',
    headers: {
      'x-timestamp': Date.now(),
      'x-sent': true
    }
  }

  const fileName = req.params.name
  res.sendFile(fileName, options, function (err) {
    if (err) {
      next(err)
    } else {
      console.log('Sent:', fileName)
    }
  })
})

The following example illustrates using res.sendFile to provide fine-grained support for serving files:

app.get('/user/:uid/photos/:file', function (req, res) {
  const uid = req.params.uid
  const file = req.params.file

  req.user.mayViewFilesFrom(uid, function (yes) {
    if (yes) {
      res.sendFile('/uploads/' + uid + '/' + file)
    } else {
      res.status(403).send("Sorry! You can't see that.")
    }
  })
})

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

res.sendStatus(statusCode)

Sets the response HTTP status code to statusCode and sends the registered status message as the text response body. If an unknown status code is specified, the response body will just be the code number.

res.sendStatus(404)

More about HTTP Status Codes

res.set(field [, value])

Sets the response’s HTTP header field to value. To set multiple fields at once, pass an object as the parameter.

res.set('Content-Type', 'text/plain')

res.set({
  'Content-Type': 'text/plain',
  'Content-Length': '123',
  ETag: '12345'
})

Aliased as res.header(field [, value]).

res.status(code)

Sets the HTTP status for the response. It is a chainable alias of Node’s response.statusCode.

res.status(403).end()
res.status(400).send('Bad Request')
res.status(404).sendFile('/absolute/path/to/404.png')

res.type(type)

Sets the Content-Type HTTP header to the MIME type as determined by the specified type. If type contains the “/” character, then it sets the Content-Type to the exact value of type, otherwise it is assumed to be a file extension and the MIME type is looked up in a mapping using the express.static.mime.lookup() method.

res.type('.html') // => 'text/html'
res.type('html') // => 'text/html'
res.type('json') // => 'application/json'
res.type('application/json') // => 'application/json'
res.type('png') // => image/png:

res.vary(field)

Adds the field to the Vary response header, if it is not there already.

res.vary('User-Agent').render('docs')

A router object is an isolated instance of middleware and routes. You can think of it as a “mini-application,” capable only of performing middleware and routing functions. Every Express application has a built-in app router.

A router behaves like middleware itself, so you can use it as an argument to app.use() or as the argument to another router’s use() method.

The top-level express object has a Router() method that creates a new router object.

Once you’ve created a router object, you can add middleware and HTTP method routes (such as get, put, post, and so on) to it just like an application. For example:

// invoked for any requests passed to this router
router.use(function (req, res, next) {
  // .. some logic here .. like any other middleware
  next()
})

// will handle any request that ends in /events
// depends on where the router is "use()'d"
router.get('/events', function (req, res, next) {
  // ..
})

You can then use a router for a particular root URL in this way separating your routes into files or even mini-apps.

// only requests to /calendar/* will be sent to our "router"
app.use('/calendar', router)

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

This method is just like the router.METHOD() methods, except that it matches all HTTP methods (verbs).

This method is extremely useful for mapping “global” logic for specific path prefixes or arbitrary matches. For example, if you placed the following route at the top of all other route definitions, it would require that all routes from that point on would 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.

router.all('*', requireAuthentication, loadUser)

Or the equivalent:

router.all('*', requireAuthentication)
router.all('*', loadUser)

Another example of this is white-listed “global” functionality. Here the example is much like before, but it only restricts paths prefixed with “/api”:

router.all('/api/*', requireAuthentication)

router.METHOD(path, [callback, ...] callback)

The router.METHOD() methods provide the routing functionality in Express, where METHOD is one of the HTTP methods, such as GET, PUT, POST, and so on, in lowercase. Thus, the actual methods are router.get(), router.post(), router.put(), and so on.

You can provide multiple callbacks, and all are treated equally, and behave just like middleware, except that these callbacks may invoke next('route') to bypass the remaining route callback(s). You can use this mechanism to perform pre-conditions on a route then pass control to subsequent routes when there is no reason to proceed with the route matched.

The following snippet illustrates the most simple route definition possible. Express translates the path strings to regular expressions, used internally to match incoming requests. Query strings are not considered when performing these matches, for example “GET /” would match the following route, as would “GET /?name=tobi”.

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

You can also use regular expressions—useful if you have very specific constraints, for example the following would match “GET /commits/71dbb9c” as well as “GET /commits/71dbb9c..4c084f9”.

router.get(/^\/commits\/(\w+)(?:\.\.(\w+))?$/, function (req, res) {
  const from = req.params[0]
  const to = req.params[1] || 'HEAD'
  res.send('commit range ' + from + '..' + to)
})

You can use next primitive to implement a flow control between different middleware functions, based on a specific program state. Invoking next with the string 'router' will cause all the remaining route callbacks on that router to be bypassed.

The following example illustrates next('router') usage.

function fn (req, res, next) {
  console.log('I come here')
  next('router')
}
router.get('/foo', fn, function (req, res, next) {
  console.log('I dont come here')
})
router.get('/foo', function (req, res, next) {
  console.log('I dont come here')
})
app.get('/foo', function (req, res) {
  console.log(' I come here too')
  res.end('good')
})

router.param(name, callback)

Adds callback triggers to route parameters, where name is the name of the parameter and callback is the callback function. Although name is technically optional, using this method without it is deprecated starting with Express v4.11.0 (see below).

The parameters of the callback function are:

• req, the request object.
• res, the response object.
• next, indicating the next middleware function.
• The value of the name parameter.
• The name of the parameter.

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.

router.param('user', function (req, res, next, id) {
  // try to get the user details from the User model and attach it to the request object
  User.find(id, function (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. Hence, param callbacks defined on router will be triggered only by route parameters defined on router routes.

A param callback will be called only once in a request-response cycle, even if the parameter is matched in multiple routes, as shown in the following examples.

router.param('id', function (req, res, next, id) {
  console.log('CALLED ONLY ONCE')
  next()
})

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

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

On GET /user/42, the following is printed:

CALLED ONLY ONCE
although this matches
and this matches too

The behavior of the router.param(name, callback) method can be altered entirely by passing only a function to router.param(). This function is a custom implementation of how router.param(name, callback) should behave - it accepts two parameters and must return a middleware.

The first parameter of this function is the name of the URL parameter that should be captured, the second parameter can be any JavaScript object which might be used for returning the middleware implementation.

The middleware returned by the function decides the behavior of what happens when a URL parameter is captured.

In this example, the router.param(name, callback) signature is modified to router.param(name, accessId). Instead of accepting a name and a callback, router.param() will now accept a name and a number.

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

// customizing the behavior of router.param()
router.param(function (param, option) {
  return function (req, res, next, val) {
    if (val === option) {
      next()
    } else {
      res.sendStatus(403)
    }
  }
})

// using the customized router.param()
router.param('id', 1337)

// route to trigger the capture
router.get('/user/:id', function (req, res) {
  res.send('OK')
})

app.use(router)

app.listen(3000, function () {
  console.log('Ready')
})

In this example, the router.param(name, callback) signature remains the same, but instead of a middleware callback, a custom data type checking function has been defined to validate the data type of the user id.

router.param(function (param, validator) {
  return function (req, res, next, val) {
    if (validator(val)) {
      next()
    } else {
      res.sendStatus(403)
    }
  }
})

router.param('id', function (candidate) {
  return !isNaN(parseFloat(candidate)) && isFinite(candidate)
})

router.route(path)

Returns an instance of a single route which you can then use to handle HTTP verbs with optional middleware. Use router.route() to avoid duplicate route naming and thus typing errors.

Building on the router.param() example above, the following code shows how to use router.route() to specify various HTTP method handlers.

const router = express.Router()

router.param('user_id', function (req, res, next, id) {
  // sample user, would actually fetch from DB, etc...
  req.user = {
    id: id,
    name: 'TJ'
  }
  next()
})

router.route('/users/:user_id')
  .all(function (req, res, next) {
  // runs for all HTTP verbs first
  // think of it as route specific middleware!
    next()
  })
  .get(function (req, res, next) {
    res.json(req.user)
  })
  .put(function (req, res, next) {
  // just an example of maybe updating the user
    req.user.name = req.params.name
    // save user ... etc
    res.json(req.user)
  })
  .post(function (req, res, next) {
    next(new Error('not implemented'))
  })
  .delete(function (req, res, next) {
    next(new Error('not implemented'))
  })

This approach re-uses the single /users/:user_id path and adds handlers for various HTTP methods.

router.use([path], [function, ...] function)

Uses the specified middleware function or functions, with optional mount path path, that defaults to “/”.

This method is similar to app.use(). A simple example and use case is described below. See app.use() for more information.

Middleware is like a plumbing pipe: requests start at the first middleware function defined and work their way “down” the middleware stack processing for each path they match.

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

// simple logger for this router's requests
// all requests to this router will first hit this middleware
router.use(function (req, res, next) {
  console.log('%s %s %s', req.method, req.url, req.path)
  next()
})

// this will only be invoked if the path starts with /bar from the mount point
router.use('/bar', function (req, res, next) {
  // ... maybe some additional /bar logging ...
  next()
})

// always invoked
router.use(function (req, res, next) {
  res.send('Hello World')
})

app.use('/foo', router)

app.listen(3000)

The “mount” path is stripped and is not visible to the middleware function. The main effect of this feature is that a mounted middleware function may operate without code changes regardless of its “prefix” pathname.

The order in which you define middleware with router.use() is very important. They are invoked sequentially, thus the order defines middleware precedence. For example, usually a logger is the very first middleware you would use, so that every request gets logged.

const logger = require('morgan')

router.use(logger())
router.use(express.static(path.join(__dirname, 'public')))
router.use(function (req, res) {
  res.send('Hello')
})

Now suppose you wanted to ignore logging requests for static files, but to continue logging routes and middleware defined after logger(). You would simply move the call to express.static() to the top, before adding the logger middleware:

router.use(express.static(path.join(__dirname, 'public')))
router.use(logger())
router.use(function (req, res) {
  res.send('Hello')
})

Another example is serving files from multiple directories, giving 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')))

The router.use() method also supports named parameters so that your mount points for other routers can benefit from preloading using named parameters.

NOTE: Although these middleware functions are added via a particular router, when they run is defined by the path they are attached to (not the router). Therefore, middleware added via one router may run for other routers if its routes match. For example, this code shows two different routers mounted on the same path:

const authRouter = express.Router()
const openRouter = express.Router()

authRouter.use(require('./authenticate').basic(usersdb))

authRouter.get('/:user_id/edit', function (req, res, next) {
  // ... Edit user UI ...
})
openRouter.get('/', function (req, res, next) {
  // ... List users ...
})
openRouter.get('/:user_id', function (req, res, next) {
  // ... View user ...
})

app.use('/users', authRouter)
app.use('/users', openRouter)

Even though the authentication middleware was added via the authRouter it will run on the routes defined by the openRouter as well since both routers were mounted on /users. To avoid this behavior, use different paths for each router.