注意：此頁面是由 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

設定在遇到「點檔」時如何處理。點檔是指以點號（「.」）開頭的檔案或目錄。請注意，此檢查會在路徑本身上執行，而不會檢查路徑是否實際存在於磁碟上。如果指定了 root，則只會檢查根目錄上方的點檔（亦即，當設定為「拒絕」時，根目錄本身可以位於點檔中）。

'allow' 不對點檔進行特殊處理。
'deny' 拒絕點檔請求，並傳回 403/next()。
'ignore' 假裝點檔不存在，並傳回 404/next()。

預設值類似於 'ignore'，但此預設值不會忽略以點號開頭的目錄中的檔案。

etag

啟用或停用 etag 產生，預設為 true。

extensions

設定檔案副檔名後備。設定後，如果找不到檔案，將會將指定的副檔名新增至檔名並搜尋。會提供找到的第一個檔案。範例：['html', 'htm']。

預設值為 false。

fallthrough

設定中間件，讓用戶端錯誤直接通過，視為未處理的要求，否則轉送用戶端錯誤。兩者之間的差別在於，當此值為 true 時，用戶端錯誤（例如錯誤的要求或對不存在檔案的要求）將導致此中間件直接 next() 到下一個中間件。當此值為 false 時，這些錯誤（甚至 404 錯誤）將呼叫 next(err)。

通常建議使用 true，這樣可以將多個實體目錄對應到同一個網路位址，或讓路由填入不存在的檔案。

如果此中間件掛載在專門設計為單一檔案系統目錄的路徑上，則可以使用 false 值，這可以讓 404 錯誤短路，減少負擔。此中間件也會回應所有方法。

預設值為 true。

immutable

在 Cache-Control 回應標頭中啟用或停用 immutable 指令，預設為 false。如果設為 true，也應該指定 maxAge 選項以啟用快取。immutable 指令將防止支援的用戶端在 maxAge 選項的存續期間發出條件式要求，以檢查檔案是否已變更。

index

預設情況下，此模組會在對目錄的要求中傳送「index.html」檔案作為回應。若要停用此功能，請設為 false，或傳遞字串或陣列（依優先順序）來提供新的索引。

lastModified

啟用或停用 Last-Modified 標頭，預設為 true。使用檔案系統的最後修改值。

maxAge

提供一個 http 快取的最大年齡（單位為毫秒），預設為 0。這也可以是一個 ms 模組所接受的字串。

重新導向

當路徑名稱為目錄時，重新導向到尾端的「/」。預設為 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