百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
S

st

> 编程语言
开源

一个用于服务静态文件的节点模块。 支持 etags、缓存等功能。

380 stars0 点赞1 次浏览
访问官网GitHub

工具介绍

一个用于服务静态文件的节点模块。 支持 etags、缓存等功能。

st

A module for serving static files. Does etags, caching, etc.

Requirements

Node.js 20 or newer. st is an ES module package.

USAGE

Here are some very simple usage examples.

Just serve the files in the cwd at the root of the http server url:

javascript
import { createServer } from 'node:http'
import st from 'st'

createServer(
  st(process.cwd())
).listen(1337)

Serve the files in static under the /static url. Otherwise do a different thing:

javascript
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { createServer } from 'node:http'
import st from 'st'

const __dirname = path.dirname(fileURLToPath(import.meta.url))
const mount = st({ path: path.join(__dirname, 'static'), url: '/static' })

createServer((req, res) => {
  const stHandled = mount(req, res)
  if (stHandled)
    return
  else
    res.end('this is not a static file')
}).listen(1338)

The same sort of thing, but using an express middleware style:

javascript
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { createServer } from 'node:http'
import st from 'st'

const __dirname = path.dirname(fileURLToPath(import.meta.url))
const mount = st({ path: path.join(__dirname, 'static'), url: '/static' })

createServer((req, res) => {
  mount(req, res, () => res.end('this is not a static file'))
}).listen(1339)

Serve the files in static under the / url, but only if not some doing other thing:

javascript
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { createServer } from 'node:http'
import st from 'st'

const __dirname = path.dirname(fileURLToPath(import.meta.url))
const mount = st({ path: path.join(__dirname, 'static'), url: '/' })

createServer((req, res) => {
  if (shouldDoThing(req)) {
    doTheThing(req, res)
  } else {
    mount(req, res)
  }
}).listen(1340)

Serve the files in static under the / url, but don't serve a 404 if the file isn't found, so that the rest of the app can handle it:

javascript
import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { createServer } from 'node:http'
import st from 'st'

const __dirname = path.dirname(fileURLToPath(import.meta.url))
const mount = st({ path: path.join(__dirname, 'static'), url: '/', passthrough: true })

createServer((req, res) => {
  mount(req, res, () => res.end('this is not a static file'))
}).listen(1341)

Serve the files with CORS enabled, to serve static files to any domain:

javascript
import { createServer } from 'node:http'
import st from 'st'

createServer(
  st({
   path: process.cwd(),
   cors: true
  })
).listen(1337)

Pass some options to the st function, and it returns a handler function.

That handler function will return true if it handles the static request, or false if it doesn't. (This is so that you can only serve static files if they're in /static for example.)

Here are some options if you want to configure stuff. All of these are optional except path which tells it where to get stuff from.

If you pass a string instead of an object, then it'll use the string as the path.

If you don't specify a url, then it'll mount on the '/' url, so st({ path: './static/' }) will try to serve ./static/foo.html when the user goes to http://example.com/foo.html. (Note: This behavior changed in st 0.2.0.)

Here are all the options described with their defaults values and a few possible settings you might choose to use:

…

On the command line:

…

Range Requests

Range requests are not supported.

I'd love a patch to add support for them, but the spec is kind of confusing, and it's not always a clear win if you're not serving very large files, so it should come with some very comprehensive tests.

Thankfully, as far as I can tell, it's always safe to serve the entire file to a request with a range header, so st does behave correctly, if not ideally in those situations. It'd be great to be able to do the better thing if the contents are cached, but still serve the full file if it's not in cache (so that it can be cached for subsequent requests).

Memory Caching

To make things go as fast as possible, it is a good idea to set the cache limits as high as you can afford, given the amount of memory on your server. Serving buffers out of process memory will generally always be faster than hitting the file system.

Client Caching

An etag header and last-modified will be attached to every request. If presented with an if-none-match or if-modified-since, then it'll return a 304 in the appropriate conditions.

The etag is generated based on the dev, ino, and last modified date. Stat results are cached.

Compression

If the request header claims to enjoy gzip encoding, and the filename does not end in '.gz' or '.tgz', then the response will be gzipped.

Gzipped bytes are not included in the calculation of cache sizes, so this utility will use a bit more memory than the cache.content.max and cache.index.max bytes would seem to allow. This will be less than double, and usually insignificant for normal web assets, but is important to consider if memory is at a premium.

Gzip compression can be disabled by setting gzip: false on the options passed into st(). This is useful if your application already handles gzipping responses by other means.

Filtering Output

If you want to do some fancy stuff to the file before sending it, you can attach a res.filter = myFilterStream thing to the response object before passing it to the mount function.

This is useful if you want to get the benefits of caching and gzipping and such, but serve stylus files as css, for example.

Security Status

Versions prior to 0.2.5 did not properly prevent folder traversal. Literal dots in a path were resolved out, but url encoded dots were not. Thus, a request like /%2e%2e/%2e%2e/%2e%2e/%2e%2e/%2e%2e/etc/passwd would leak sensitive data from the server.

Versions prior to 3.0.4 performed one traversal check before a later percent-decode step. In configurations with dot: true, encoded separators and dots could reintroduce ../ after that check.

Current releases percent-decode before traversal validation, reject decoded .. path segments, and also validate that the resolved filesystem path stays inside the configured root. If your application depends on .. in URL paths, please refactor so that it does not depend on traversal-like URLs.

Consider using the --localhost setting if you don't want other people on your local network to read the files served by the command line server. This may become the default in a future major version.

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

JavaScript

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言