Projekt

Obecné

Profil

Stáhnout (7.6 KB) Statistiky
| Větev: | Revize:
1
# serve-static
2

    
3
[![NPM Version][npm-version-image]][npm-url]
4
[![NPM Downloads][npm-downloads-image]][npm-url]
5
[![Linux Build][travis-image]][travis-url]
6
[![Windows Build][appveyor-image]][appveyor-url]
7
[![Test Coverage][coveralls-image]][coveralls-url]
8

    
9
## Install
10

    
11
This is a [Node.js](https://nodejs.org/en/) module available through the
12
[npm registry](https://www.npmjs.com/). Installation is done using the
13
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
14

    
15
```sh
16
$ npm install serve-static
17
```
18

    
19
## API
20

    
21
<!-- eslint-disable no-unused-vars -->
22

    
23
```js
24
var serveStatic = require('serve-static')
25
```
26

    
27
### serveStatic(root, options)
28

    
29
Create a new middleware function to serve files from within a given root
30
directory. The file to serve will be determined by combining `req.url`
31
with the provided root directory. When a file is not found, instead of
32
sending a 404 response, this module will instead call `next()` to move on
33
to the next middleware, allowing for stacking and fall-backs.
34

    
35
#### Options
36

    
37
##### acceptRanges
38

    
39
Enable or disable accepting ranged requests, defaults to true.
40
Disabling this will not send `Accept-Ranges` and ignore the contents
41
of the `Range` request header.
42

    
43
##### cacheControl
44

    
45
Enable or disable setting `Cache-Control` response header, defaults to
46
true. Disabling this will ignore the `immutable` and `maxAge` options.
47

    
48
##### dotfiles
49

    
50
 Set how "dotfiles" are treated when encountered. A dotfile is a file
51
or directory that begins with a dot ("."). Note this check is done on
52
the path itself without checking if the path actually exists on the
53
disk. If `root` is specified, only the dotfiles above the root are
54
checked (i.e. the root itself can be within a dotfile when set
55
to "deny").
56

    
57
  - `'allow'` No special treatment for dotfiles.
58
  - `'deny'` Deny a request for a dotfile and 403/`next()`.
59
  - `'ignore'` Pretend like the dotfile does not exist and 404/`next()`.
60

    
61
The default value is similar to `'ignore'`, with the exception that this
62
default will not ignore the files within a directory that begins with a dot.
63

    
64
##### etag
65

    
66
Enable or disable etag generation, defaults to true.
67

    
68
##### extensions
69

    
70
Set file extension fallbacks. When set, if a file is not found, the given
71
extensions will be added to the file name and search for. The first that
72
exists will be served. Example: `['html', 'htm']`.
73

    
74
The default value is `false`.
75

    
76
##### fallthrough
77

    
78
Set the middleware to have client errors fall-through as just unhandled
79
requests, otherwise forward a client error. The difference is that client
80
errors like a bad request or a request to a non-existent file will cause
81
this middleware to simply `next()` to your next middleware when this value
82
is `true`. When this value is `false`, these errors (even 404s), will invoke
83
`next(err)`.
84

    
85
Typically `true` is desired such that multiple physical directories can be
86
mapped to the same web address or for routes to fill in non-existent files.
87

    
88
The value `false` can be used if this middleware is mounted at a path that
89
is designed to be strictly a single file system directory, which allows for
90
short-circuiting 404s for less overhead. This middleware will also reply to
91
all methods.
92

    
93
The default value is `true`.
94

    
95
##### immutable
96

    
97
Enable or disable the `immutable` directive in the `Cache-Control` response
98
header, defaults to `false`. If set to `true`, the `maxAge` option should
99
also be specified to enable caching. The `immutable` directive will prevent
100
supported clients from making conditional requests during the life of the
101
`maxAge` option to check if the file has changed.
102

    
103
##### index
104

    
105
By default this module will send "index.html" files in response to a request
106
on a directory. To disable this set `false` or to supply a new index pass a
107
string or an array in preferred order.
108

    
109
##### lastModified
110

    
111
Enable or disable `Last-Modified` header, defaults to true. Uses the file
112
system's last modified value.
113

    
114
##### maxAge
115

    
116
Provide a max-age in milliseconds for http caching, defaults to 0. This
117
can also be a string accepted by the [ms](https://www.npmjs.org/package/ms#readme)
118
module.
119

    
120
##### redirect
121

    
122
Redirect to trailing "/" when the pathname is a dir. Defaults to `true`.
123

    
124
##### setHeaders
125

    
126
Function to set custom headers on response. Alterations to the headers need to
127
occur synchronously. The function is called as `fn(res, path, stat)`, where
128
the arguments are:
129

    
130
  - `res` the response object
131
  - `path` the file path that is being sent
132
  - `stat` the stat object of the file that is being sent
133

    
134
## Examples
135

    
136
### Serve files with vanilla node.js http server
137

    
138
```js
139
var finalhandler = require('finalhandler')
140
var http = require('http')
141
var serveStatic = require('serve-static')
142

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

    
146
// Create server
147
var server = http.createServer(function onRequest (req, res) {
148
  serve(req, res, finalhandler(req, res))
149
})
150

    
151
// Listen
152
server.listen(3000)
153
```
154

    
155
### Serve all files as downloads
156

    
157
```js
158
var contentDisposition = require('content-disposition')
159
var finalhandler = require('finalhandler')
160
var http = require('http')
161
var serveStatic = require('serve-static')
162

    
163
// Serve up public/ftp folder
164
var serve = serveStatic('public/ftp', {
165
  'index': false,
166
  'setHeaders': setHeaders
167
})
168

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

    
174
// Create server
175
var server = http.createServer(function onRequest (req, res) {
176
  serve(req, res, finalhandler(req, res))
177
})
178

    
179
// Listen
180
server.listen(3000)
181
```
182

    
183
### Serving using express
184

    
185
#### Simple
186

    
187
This is a simple example of using Express.
188

    
189
```js
190
var express = require('express')
191
var serveStatic = require('serve-static')
192

    
193
var app = express()
194

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

    
199
#### Multiple roots
200

    
201
This example shows a simple way to search through multiple directories.
202
Files are look for in `public-optimized/` first, then `public/` second as
203
a fallback.
204

    
205
```js
206
var express = require('express')
207
var path = require('path')
208
var serveStatic = require('serve-static')
209

    
210
var app = express()
211

    
212
app.use(serveStatic(path.join(__dirname, 'public-optimized')))
213
app.use(serveStatic(path.join(__dirname, 'public')))
214
app.listen(3000)
215
```
216

    
217
#### Different settings for paths
218

    
219
This example shows how to set a different max age depending on the served
220
file type. In this example, HTML files are not cached, while everything else
221
is for 1 day.
222

    
223
```js
224
var express = require('express')
225
var path = require('path')
226
var serveStatic = require('serve-static')
227

    
228
var app = express()
229

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

    
235
app.listen(3000)
236

    
237
function setCustomCacheControl (res, path) {
238
  if (serveStatic.mime.lookup(path) === 'text/html') {
239
    // Custom Cache-Control for HTML files
240
    res.setHeader('Cache-Control', 'public, max-age=0')
241
  }
242
}
243
```
244

    
245
## License
246

    
247
[MIT](LICENSE)
248

    
249
[appveyor-image]: https://badgen.net/appveyor/ci/dougwilson/serve-static/master?label=windows
250
[appveyor-url]: https://ci.appveyor.com/project/dougwilson/serve-static
251
[coveralls-image]: https://badgen.net/coveralls/c/github/expressjs/serve-static/master
252
[coveralls-url]: https://coveralls.io/r/expressjs/serve-static?branch=master
253
[node-image]: https://badgen.net/npm/node/serve-static
254
[node-url]: https://nodejs.org/en/download/
255
[npm-downloads-image]: https://badgen.net/npm/dm/serve-static
256
[npm-url]: https://npmjs.org/package/serve-static
257
[npm-version-image]: https://badgen.net/npm/v/serve-static
258
[travis-image]: https://badgen.net/travis/expressjs/serve-static/master?label=linux
259
[travis-url]: https://travis-ci.org/expressjs/serve-static
(3-3/5)