注意： 此页面由 serve-static README 生成。

serve-static

安装

这是一个通过 npm 注册表可用的 Node.js 模块。安装使用 npm install 命令

$ npm install serve-static

API

var serveStatic = require('serve-static')

serveStatic(root, options)

创建一个新的中间件函数，用于从给定的根目录中提供文件。要提供的文件将通过将 req.url 与提供的根目录组合来确定。当找不到文件时，此模块不会发送 404 响应，而是调用 next() 以继续执行下一个中间件，从而允许堆叠和回退。

选项

acceptRanges

启用或禁用接受范围请求，默认为 true。禁用此选项将不会发送 Accept-Ranges 并忽略 Range 请求标头的内容。

cacheControl

启用或禁用设置 Cache-Control 响应标头，默认为 true。禁用此选项将忽略 immutable 和 maxAge 选项。

dotfiles

设置遇到“dotfiles”时的处理方式。dotfile 是以点（“.”）开头的文件或目录。请注意，此检查是在路径本身进行的，不检查路径是否实际存在于磁盘上。如果指定了root，则只检查根目录以上的 dotfiles（即，当设置为“deny”时，根目录本身可以位于 dotfile 内）。

'allow' 对 dotfiles 不进行特殊处理。
'deny' 拒绝 dotfile 请求并返回 403/next()。
'ignore' 假装 dotfile 不存在并返回 404/next()。

默认值类似于 'ignore'，但区别在于此默认值不会忽略以点开头的目录中的文件。

etag

启用或禁用 etag 生成，默认值为 true。

extensions

设置文件扩展名回退。如果设置了此选项，则如果找不到文件，将向文件名添加给定的扩展名并进行搜索。找到第一个存在的扩展名将被使用。例如：['html', 'htm']。

默认值为 false。

fallthrough

设置中间件，使客户端错误作为未处理请求直接通过，否则转发客户端错误。区别在于，当此值为 true 时，客户端错误（如错误请求或对不存在文件的请求）将导致此中间件简单地 next() 到您的下一个中间件。当此值为 false 时，这些错误（即使是 404 错误）将调用 next(err)。

通常希望 true，这样多个物理目录可以映射到同一个 Web 地址，或者路由可以填充不存在的文件。

如果此中间件安装在旨在严格作为单个文件系统目录的路径上，则可以使用 false 值，这允许对 404 错误进行短路，以减少开销。此中间件也将回复所有方法。

默认值为 true。

immutable

在 Cache-Control 响应头中启用或禁用 immutable 指令，默认值为 false。如果设置为 true，则还应指定 maxAge 选项以启用缓存。immutable 指令将阻止支持的客户端在 maxAge 选项的生命周期内发出条件请求以检查文件是否已更改。

index

默认情况下，此模块将在目录上的请求响应中发送“index.html”文件。要禁用此功能，请设置为 false，或要提供新的索引，请按优先顺序传递字符串或数组。

lastModified

启用或禁用 Last-Modified 标头，默认值为 true。使用文件系统的最后修改值。

maxAge

提供以毫秒为单位的 http 缓存最大年龄，默认值为 0。这也可以是 ms 模块接受的字符串。

redirect

当路径名是目录时，重定向到尾部的“/”。默认值为 true。

setHeaders

用于在响应中设置自定义标头的函数。对标头的更改需要同步发生。该函数以 fn(res, path, stat) 的形式调用，其中参数为

res 响应对象
path 正在发送的文件路径
stat 正在发送的文件的 stat 对象

示例

使用原生 node.js http 服务器提供文件

var finalhandler = require('finalhandler')
var http = require('http')
var serveStatic = require('serve-static')

// Serve up public/ftp folder
var serve = serveStatic('public/ftp', { index: ['index.html', 'index.htm'] })

// Create server
var server = http.createServer(function onRequest (req, res) {
  serve(req, res, finalhandler(req, res))
})

// Listen
server.listen(3000)

将所有文件作为下载提供

var contentDisposition = require('content-disposition')
var finalhandler = require('finalhandler')
var http = require('http')
var serveStatic = require('serve-static')

// Serve up public/ftp folder
var serve = serveStatic('public/ftp', {
  index: false,
  setHeaders: setHeaders
})

// Set header to force download
function setHeaders (res, path) {
  res.setHeader('Content-Disposition', contentDisposition(path))
}

// Create server
var server = http.createServer(function onRequest (req, res) {
  serve(req, res, finalhandler(req, res))
})

// Listen
server.listen(3000)

使用 express 提供服务

简单

这是一个使用 Express 的简单示例。

var express = require('express')
var serveStatic = require('serve-static')

var app = express()

app.use(serveStatic('public/ftp', { index: ['default.html', 'default.htm'] }))
app.listen(3000)

多个根目录

此示例展示了一种简单的方法来搜索多个目录。首先在 public-optimized/ 中搜索文件，然后在 public/ 中作为回退进行搜索。

var express = require('express')
var path = require('path')
var serveStatic = require('serve-static')

var app = express()

app.use(serveStatic(path.join(__dirname, 'public-optimized')))
app.use(serveStatic(path.join(__dirname, 'public')))
app.listen(3000)

不同路径的不同设置

此示例展示了如何根据提供服务的文件类型设置不同的最大年龄。在此示例中，HTML 文件不会被缓存，而其他所有文件则缓存 1 天。

var express = require('express')
var path = require('path')
var serveStatic = require('serve-static')

var app = express()

app.use(serveStatic(path.join(__dirname, 'public'), {
  maxAge: '1d',
  setHeaders: setCustomCacheControl
}))

app.listen(3000)

function setCustomCacheControl (res, path) {
  if (serveStatic.mime.lookup(path) === 'text/html') {
    // Custom Cache-Control for HTML files
    res.setHeader('Cache-Control', 'public, max-age=0')
  }
}

许可证

MIT