Ecstatic 项目技术文档

1. 安装指南

1.1 使用 npm 安装

1.1.1 作为库安装

要将 Ecstatic 作为库安装到你的项目中，请在项目目录下运行以下命令：

npm install --save ecstatic

1.1.2 作为 CLI 工具安装

如果你希望将 Ecstatic 作为命令行工具使用，可以全局安装：

npm install ecstatic -g

或者，你也可以在本地安装并使用 npm runscripts 将其添加到 $PATH，或者直接引用 ./node_modules/.bin/ecstatic。

2. 项目的使用说明

2.1 使用示例

2.1.1 与 Express 4.x 一起使用

'use strict';

const express = require('express');
const ecstatic = require('ecstatic');
const http = require('http');

const app = express();

app.use(ecstatic({
  root: `${__dirname}/public`,
  showdir: true,
}));

http.createServer(app).listen(8080);

console.log('Listening on :8080');

2.1.2 使用原生 HTTP 服务器

'use strict';

const http = require('http');

const ecstatic = require('ecstatic')({
  root: `${__dirname}/public`,
  showDir: true,
  autoIndex: true,
});

http.createServer(ecstatic).listen(8080);

console.log('Listening on :8080');

2.1.3 允许 fall through

ecstatic({ root: __dirname + '/public', handleError: false })

2.1.4 使用 CLI

ecstatic ./public --port 8080

3. 项目API使用文档

3.1 ecstatic(opts)

在 Node.js 中，传递一个选项对象给 ecstatic，它将返回一个中间件函数。

const opts = {
  root: path.join(__dirname, 'public'),
  baseDir: '/',
  autoIndex: true,
  showDir: true,
  showDotfiles: true,
  humanReadable: true,
  hidePermissions: false,
  si: false,
  cache: 'max-age=3600',
  cors: false,
  gzip: true,
  brotli: false,
  defaultExt: 'html',
  handleError: true,
  serverHeader: true,
  contentType: 'application/octet-stream',
  weakEtags: true,
  weakCompare: true,
  handleOptionsMethod: false,
}

如果 opts 是一个字符串，它将被分配给 root 文件夹，其他选项将设置为默认值。

3.2 CLI 模式

在 CLI 模式下，所有选项都与上述相同，但通过 optimist 风格传递。port 默认值为 8000。如果没有传递 dir 或 --root dir 参数，Ecstatic 将服务当前目录。Ecstatic 还尊重 PORT 环境变量。

3.3 选项详解

3.3.1 opts.root / --root {root}

opts.root 是你希望服务的目录。

3.3.2 opts.host / --host {host}

在 CLI 模式下，opts.host 是你希望 Ecstatic 监听的主机。默认值为 0.0.0.0。可以通过 --host 标志或 HOST 环境变量覆盖。

3.3.3 opts.port / --port {port}

在 CLI 模式下，opts.port 是你希望 Ecstatic 监听的端口。默认值为 8000。可以通过 --port 标志或 PORT 环境变量覆盖。

3.3.4 opts.baseDir / --baseDir {dir}

opts.baseDir 默认为 /，但可以更改以允许你的静态文件从特定路由提供服务。

3.3.5 opts.cache / --cache {value}

自定义缓存控制。

3.3.6 opts.showDir / --no-showDir

关闭目录列表。

3.3.7 opts.showDotfiles / --no-showDotfiles

从目录列表中排除点文件。

3.3.8 opts.humanReadable / --no-human-readable

如果启用了 showDir，添加人类可读的文件大小。

3.3.9 opts.hidePermissions / --hide-permissions

如果启用了 hidePermissions，文件权限将不会显示。

3.3.10 opts.headers / --H {HeaderA: valA} [--H {HeaderB: valB}]

在每个响应上设置头。

3.3.11 opts.si / --si

如果启用了 showDir 和 humanReadable，打印文件大小时使用基数 1000 而不是基数 1024。

3.3.12 opts.autoIndex / --no-autoindex

当请求 /path/ 时，服务 /path/index.html。

3.3.13 opts.defaultExt / --defaultExt {ext}

启用默认文件扩展名。

3.3.14 opts.gzip / --no-gzip

默认情况下，Ecstatic 将服务 ./public/some-file.js.gz 而不是 ./public/some-file.js。

3.3.15 opts.brotli / --brotli

服务 ./public/some-file.js.br 而不是 ./public/some-file.js。

3.3.16 opts.serverHeader / --no-server-header

设置 opts.serverHeader 为 false 以关闭在所有响应上设置 Server 头。

3.3.17 opts.contentType / --content-type {type}

设置默认的 Content-Type 头值。

3.3.18 opts.mimeTypes / --mime-types {filename}

添加新的或覆盖一个或多个 MIME 类型。

3.3.19 opts.handleError

关闭 handleErrors 以允许 fall-through。

3.3.20 opts.weakEtags / --no-weak-etags

设置 opts.weakEtags 为 false 以生成强 ETag 而不是弱 ETag。

3.3.21 opts.weakCompare / --no-weak-compare

关闭 weakCompare 以禁用弱比较函数。

3.3.22 opts.handleOptionsMethod / --handle-options-method

设置 handleOptionsMethod 为 true 以响应 OPTIONS 调用。

3.3.23 opts.cors / --cors

这是一个便利设置，用于快速启用跨域资源共享。

4. 项目安装方式

4.1 使用 npm 安装

npm install --save ecstatic

4.2 全局安装 CLI 工具

npm install ecstatic -g

4.3 本地安装并使用

npm install ecstatic

然后可以使用 ./node_modules/.bin/ecstatic 来运行 CLI 工具。