Static

Static ミドルウェアはルートディレクトリからファイルを配信します。この例では / で public/index.html を配信します。

使い方

echox のソースディレクトリで cd reference/static && go run . を実行し、http://localhost:1323/ を開いてください。

// SPDX-License-Identifier: MIT

// This complete example is the source for the Static middleware documentation.
package main

import (
  "github.com/labstack/echo/v5"
  "github.com/labstack/echo/v5/middleware"
)

func main() {
  e := echo.New()
  e.Use(middleware.StaticWithConfig(middleware.StaticConfig{
    Root:                 "public",
    EnablePathUnescaping: false, // Keep encoded slashes encoded when route guards protect files.
  }))

  if err := e.Start(":1323"); err != nil {
    e.Logger.Error("server stopped", "error", err)
  }
}

このページはドキュメントの CI がコンパイルするファイルをそのまま読み込みます。この例の EnablePathUnescaping は false で、エンコードされたスラッシュに対する安全な既定値です。

カスタム設定

Root は配信するディレクトリです。Browse はディレクトリ一覧を有効にし、HTML5 は見つからないパスをインデックスファイルに転送し、Filesystem には fs.FS を指定できます。グループの URL プレフィックスをファイルパスに含めたくない場合は IgnoreBase を使います。

Echo v5.4.0 の HTML5 は、ルーターが返した 404 の場合だけインデックスを配信します。一致したルート自身が返す 404 はそのまま返します。SPA と API を同じサーバーで扱う場合に重要です。

例 1

ルート以外のグループに Static ミドルウェアを設定すると、通常はグループの URL プレフィックスがファイルパスに含まれます。ファイルシステムのルートがすでにその場所を指している場合は IgnoreBase: true を設定します。グループのミドルウェアを実行するには、一致するルートが必要です。

例 2

埋め込みファイルシステムを配信するには、Filesystem に embed.FS、Root にその中のアセットディレクトリを設定します。完全なプログラムは埋め込みリソースのクックブックを参照してください。

設定

この表は、記載された Echo リビジョンの公開フィールドから生成されます。非推奨フィールドを示しますが、デフォルト値やセキュリティ上の動作は推測しません。

StaticConfig · github.com/labstack/echo/v5@5196b9b

フィールドの説明は英語のソースコードのコメントから生成されています。

パッケージのソースコードのフィールド
フィールド	型	説明	ソース
`Skipper`	`Skipper`	Skipper defines a function to skip middleware.	L26
`Root`	`string`	Root directory from where the static content is served (relative to given Filesystem). `Root: "."` means root folder from Filesystem. Required.	L31
`Filesystem`	`fs.FS`	Filesystem provides access to the static content. Optional. Defaults to echo.Filesystem (serves files from `.` folder where executable is started)	L35
`Index`	`string`	Index file for serving a directory. Optional. Default value "index.html".	L39
`HTML5`	`bool`	Enable HTML5 mode by forwarding all not-found requests to root so that SPA (single-page application) can handle the routing. Optional. Default value false.	L44
`Browse`	`bool`	Enable directory browsing. Optional. Default value false.	L48
`IgnoreBase`	`bool`	Enable ignoring of the base of the URL path. Example: when assigning a static middleware to a non root path group, the filesystem path is not doubled Optional. Default value false.	L54
`DisablePathUnescaping`非推奨	`bool`	Deprecated: this field is ignored, use EnablePathUnescaping instead. DisablePathUnescaping will be removed in a future version. Note: previously the zero value (false) enabled unescaping, which was the unsafe default.	L58
`EnablePathUnescaping`	`bool`	EnablePathUnescaping enables unescaping of the request path (or of the wildcard param `` when the middleware is used on a wildcard route) before the file is looked up. Default false (safe): the path is used in the same form as the router matched it, so encoded characters such as encoded slashes (%2f) are NOT decoded, preventing ACL bypass where /admin%2fprivate.txt bypasses a /admin/ route guard by not matching that route but being decoded to admin/private.txt. As a consequence, file names that the client sends with non-default escaping (e.g. `%2C`, `%40` or lowercase hex like `%c3%a9`) are not found. Set to true only when serving files whose names need such unescaping and you are not relying on route-based ACL guards to restrict access. Paths with ".", ".." or empty segments are never served, also after unescaping. Enabling echo.RouterConfig.UseEscapedPathForMatching makes this field irrelevant and can lead to security issues when using different Routes to exclude some of the files from being served. e.g. if you serve files from directory as such and use different route to exclude some of the files from being served. 0. given folder structure: public/ public/index.html public/admin/private.txt 1. share `public/` folder contents from the server root with `e.Static("/", "public")` 2. naively assume that everything under /admin folder is now forbidden e.GET("/admin/", func(c Context) error { return echo.ErrForbidden }) Then request to `/assets/../admin%2fprivate.txt` will be served as router does not match it to guarded route.	L80
`DirectoryListTemplate`	`string`	DirectoryListTemplate is template to list directory contents Optional. Default to `directoryListHTMLTemplate` constant below.	L84

パッケージのソースコードの関数
型	ソース
`func Static(root string) echo.MiddlewareFunc`	L170
`func StaticWithConfig(config StaticConfig) echo.MiddlewareFunc`	L177

デフォルト設定

Index の既定値は index.html です。EnablePathUnescaping の既定値は false で、ワイルドカードパス内のエンコードされたスラッシュをデコードしません。DisablePathUnescaping は非推奨で、現在の Echo では無視されます。明示的にデコードが必要な場合は EnablePathUnescaping を使います。

ファイル名に URL エンコードされた文字が必要で、ルートでサブディレクトリへのアクセスを制限していない場合にのみ有効にしてください。ルーティング後にスラッシュをデコードすると、保護用ルートを回避できる場合があります。

Echo のセキュリティ更新 (v5.4.0 / v4.16.0)

既定では、Static はルーターが照合した形式のパスからファイルを解決します。標準以外のエスケープを使ったファイル名（%2C、%40、小文字の 16 進数など）には EnablePathUnescaping が必要です。.、..、空のセグメント（例: /assets//app.js）は 404 になり、HTML5 モードではインデックスを返す場合があります。パスのデコードはエンコードされたスラッシュも復元するため、サブディレクトリのルート単位のアクセス制御と併用しないでください。e.Use(middleware.Static(...)) はルート・グループのミドルウェアより先に実行されます。保護するファイルはそのルート外に置くか、ガード付きの Echo#Static で配信してください。