注: このページは、serve-static の README から生成されました。

serve-static

インストール

これは、Node.js モジュールであり、npm レジストリから利用できます。インストールは、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」に設定すると、ルート自体をドットファイル内に配置できます）。

'allow' ドットファイルに対して特別な処理を行いません。
'deny' ドットファイルへのリクエストを拒否し、403/next() を返します。
'ignore' ドットファイルが存在しないかのように扱い、404/next() を返します。

デフォルト値は 'ignore' と似ていますが、このデフォルトでは、ドットで始まるディレクトリ内のファイルは無視されない点が異なります。

etag

etag の生成を有効または無効にします。デフォルトは true です。

extensions

ファイル拡張子のフォールバックを設定します。設定すると、ファイルが見つからない場合、指定された拡張子がファイル名に追加され、検索されます。最初に存在するファイルが提供されます。例：['html', 'htm']。

デフォルト値は false です。

fallthrough

クライアントエラーを未処理のリクエストとしてフォールスルーさせるか、クライアントエラーを転送するようにミドルウェアを設定します。違いは、無効なリクエストや存在しないファイルへのリクエストなどのクライアントエラーが、この値が true の場合、このミドルウェアを単に next() して次のミドルウェアに進ませることです。この値が false の場合、これらのエラー（404 なども含む）は next(err) を呼び出します。

通常、複数の物理ディレクトリを同じ Web アドレスにマップしたり、存在しないファイルをルートで埋める場合など、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 モジュールで受け入れられる文字列にすることもできます。

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