注意

本页面根据 serve-static README 生成。

serve-static

NPM Version NPM Downloads CI Test Coverage

安装

这是一个通过 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

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

默认值为 '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) 的形式调用，其中参数是

示例

使用普通 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, file) {
  if (path.extname(file) === '.html') {
    // Custom Cache-Control for HTML files
    res.setHeader('Cache-Control', 'public, max-age=0')
  }
}

许可证

MIT