Static File Service Configuration

By default, the GoFrame Server disables the static file service feature. If the developer configures a static file directory, the static file service will be automatically enabled.

Common configuration methods involving the static file service are as follows:

// Set HTTP server parameter - ServerRoot
func (s *Server) SetServerRoot(root string)
// Add static file search directories; the absolute path of the directory must be specified
func (s *Server) AddSearchPath(path string)
// Set HTTP server parameter - IndexFiles, default displayed files, such as: index.html, index.htm
func (s *Server) SetIndexFiles(index []string)
// Allow or disallow displaying the directory listing of accessible directories
func (s *Server) SetIndexFolder(enabled bool)
// Add mapping of URI to static directory
func (s *Server) AddStaticPath(prefix string, path string)
// Main switch for static file service: enable/disable static file service
func (s *Server) SetFileServerEnabled(enabled bool)
// Set URI rewrite rule
func (s *Server) SetRewrite(uri string, rewrite string)
// Set URI rewrite rules (batch)
func (s *Server) SetRewriteMap(rewrites map[string]string)

Brief introduction:

1. IndexFiles is the list of default file names searched when accessing directories (searched in the order of the slice). If the searched file exists, the file content is returned; otherwise, the directory listing is displayed (when SetIndexFolder is true). The default IndexFiles are: index.html, index.htm.
2. SetIndexFolder is set to allow displaying the file list in the directory when users access a file directory and no IndexFiles are found in the directory. It is disabled by default.
3. SetServerRoot sets the default static file directory for services. This directory is automatically added as the first search path in SearchPath.
4. AddSearchPath adds static file search directories, which can be multiple, and priority searches are performed in the order of added file directories.
5. AddStaticPath adds mapping relationships between URI and directory paths, allowing customization of static file directory access URI rules.
6. SetRewrite/SetRewriteMap sets rewrite rules (similar to nginx rewrite), which technically apply not only to static file services but also support dynamic route registration rewrite.

tip

When setting the directory path for the static file service, you can use either absolute or relative paths. For example, to set the current running directory to provide static file services, use SetServerRoot(".").

Developers can set multiple file directories to provide static file services and prioritize directories and URIs. However, if the static service is disabled via SetFileServerEnabled, all static file/directory access will become invalid.

Example 1, Basic Usage

package main
import "github.com/gogf/gf/v2/frame/g"
// Basic usage of static file server
func main() {
    s := g.Server()
    s.SetIndexFolder(true)
    s.SetServerRoot("/Users/john/Temp")
    s.AddSearchPath("/Users/john/Documents")
    s.SetPort(8199)
    s.Run()
}

Example 2, Static Directory Mapping

package main
import "github.com/gogf/gf/v2/frame/g"
// Static file server supports custom static directory mapping
func main() {
    s := g.Server()
    s.SetIndexFolder(true)
    s.SetServerRoot("/Users/john/Temp")
    s.AddSearchPath("/Users/john/Documents")
    s.AddStaticPath("/my-doc", "/Users/john/Documents")
    s.SetPort(8199)
    s.Run()
}

Example 3, Static Directory Mapping, Priority Control

The priority of static directory mapping is controlled according to the precision of the bound URI. The more precise the bound URI (depth-first matching), the higher the priority.

package main
import "github.com/gogf/gf/v2/frame/g"
// Static file server supports custom static directory mapping
func main() {
    s := g.Server()
    s.SetIndexFolder(true)
    s.SetServerRoot("/Users/john/Temp")
    s.AddSearchPath("/Users/john/Documents")
    s.AddStaticPath("/my-doc", "/Users/john/Documents")
    s.AddStaticPath("/my-doc/test", "/Users/john/Temp")
    s.SetPort(8199)
    s.Run()
}

Here, accessing /my-doc/test has a higher priority than /my-doc. Therefore, if there is a test directory under /Users/john/Documents (conflicting with the custom /my-doc/test), it cannot be accessed.

Example 4, URI Rewrite

The static file service of the GoFrame framework supports rewriting any URI to replace it with a designated URI, using SetRewrite/SetRewriteMap methods.

Example: In the /Users/john/Temp directory, there are only two files test1.html and test2.html.

package main
import "github.com/gogf/gf/v2/frame/g"
func main() {
    s := g.Server()
    s.SetServerRoot("/Users/john/Temp")
    s.SetRewrite("/test.html", "/test1.html")
    s.SetRewriteMap(g.MapStrStr{
        "/my-test1": "/test1.html",
        "/my-test2": "/test2.html",
    })
    s.SetPort(8199)
    s.Run()
}

After execution,

1. When accessing /test.html, it is eventually rewritten to test1.html, and the content of this file is returned.
2. When accessing /my-test1, it is eventually rewritten to test1.html, and the content of this file is returned.
3. When accessing /my-test2, it is eventually rewritten to test2.html, and the content of this file is returned.

Example 5, Cross-Origin

package main
import (
    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/net/ghttp"
    "github.com/gogf/gf/v2/os/glog"
)
func beforeServeHook(r *ghttp.Request) {
    glog.Debugf(r.GetCtx(), "beforeServeHook [is file:%v] URI:%s", r.IsFileRequest(), r.RequestURI)
    r.Response.CORSDefault()
}
// Use hooks to inject cross-origin configuration
func main() {
    s := g.Server()
    s.BindHookHandler("/*", ghttp.HookBeforeServe, beforeServeHook)
    s.SetServerRoot(".")
    s.SetFileServerEnabled(true)
    s.SetAddr(":8080")
    s.Run()
}