第四章：静态文件服务¶

Caddy 可以作为高效的静态文件服务器，配置简单且性能优秀。

基本静态文件服务¶

最简配置¶

example.com {
    root * /var/www/html
    file_server
}

就这么简单！Caddy 会： - 自动设置 MIME 类型 - 启用 Gzip 压缩 - 处理范围请求（断点续传）

启用目录浏览¶

files.example.com {
    root * /var/www/files
    file_server browse
}

访问时会显示文件列表，支持： - 文件图标 - 文件大小 - 修改时间 - 排序功能

路径配置¶

指定根目录¶

example.com {
    root * /var/www/html
    file_server
}

不同路径不同目录¶

example.com {
    # 主站
    root * /var/www/main
    file_server

    # 静态资源子路径
    handle /static/* {
        root * /var/www/static
        file_server
    }

    # 下载文件
    handle /downloads/* {
        root * /var/www/downloads
        file_server browse
    }
}

URL 重写¶

example.com {
    root * /var/www/html
    file_server

    # SPA 应用支持
    @notStatic not path /js/* /css/* /images/* /fonts/*
    rewrite @notStatic /index.html
}

文件处理¶

索引文件¶

默认查找 index.html，可自定义：

example.com {
    root * /var/www/html

    # 自定义索引文件
    file_server {
        index index.html index.htm default.html
    }
}

隐藏文件¶

默认不显示隐藏文件（以 . 开头），可配置：

example.com {
    root * /var/www/html
    file_server {
        # 显示隐藏文件
        hide .git .env
    }
}

预压缩文件¶

Caddy 支持自动提供预压缩文件：

example.com {
    root * /var/www/html
    file_server {
        precompressed gzip br zstd
    }
}

如果请求 style.css，Caddy 会按顺序查找： 1. style.css.gz 2. style.css.br 3. style.css.zstd 4. style.css（原始文件）

压缩配置¶

Caddy 默认启用 Gzip 压缩，可自定义：

example.com {
    root * /var/www/html

    # 启用多种压缩算法
    encode gzip zstd br

    file_server
}

压缩级别¶

example.com {
    encode {
        gzip 6
        zstd
    }
    root * /var/www/html
    file_server
}

缓存控制¶

静态资源缓存¶

example.com {
    root * /var/www/html

    # 长期缓存静态资源
    @static path /js/* /css/* /images/* /fonts/*
    header @static Cache-Control "public, max-age=31536000, immutable"

    # HTML 不缓存
    @html path *.html
    header @html Cache-Control "no-cache"

    file_server
}

ETag 支持¶

Caddy 自动生成 ETag，无需配置：

# Caddy 自动处理
# If-None-Match: "etag-value"
# 响应 304 Not Modified

访问控制¶

基于路径的访问控制¶

example.com {
    root * /var/www/html

    # 禁止访问敏感目录
    @blocked path /private/* /admin/* /.git/*
    respond @blocked "Access Denied" 403

    file_server
}

基于 IP 的访问控制¶

example.com {
    root * /var/www/html

    # 只允许特定 IP 访问
    @internal {
        remote_ip 192.168.1.0/24 10.0.0.0/8
    }

    @blocked not remote_ip 192.168.1.0/24 10.0.0.0/8
    respond @blocked "Forbidden" 403

    file_server
}

基础认证¶

admin.example.com {
    root * /var/www/admin

    basicauth * {
        admin $2a$14$Zkx9...
    }

    file_server
}

单页应用（SPA）¶

Vue/React SPA 配置¶

app.example.com {
    root * /var/www/app

    # 静态资源直接服务
    @static path /assets/* /js/* /css/* /images/* /fonts/*
    file_server @static

    # 其他请求返回 index.html
    @notStatic not path /assets/* /js/* /css/* /images/* /fonts/*
    rewrite @notStatic /index.html

    file_server
}

更简洁的写法¶

app.example.com {
    root * /var/www/app

    try_files {path} /index.html
    file_server
}

虚拟主机¶

多站点配置¶

# 网站 A
site-a.com {
    root * /var/www/site-a
    file_server
}

# 网站 B
site-b.com {
    root * /var/www/site-b
    file_server browse
}

# 网站 C（带认证）
site-c.com {
    root * /var/www/site-c
    basicauth * {
        user $2a$14$hash...
    }
    file_server
}

子域名配置¶

# 主站
example.com {
    root * /var/www/main
    file_server
}

# 文档站点
docs.example.com {
    root * /var/www/docs
    file_server
}

# API（反向代理）
api.example.com {
    reverse_proxy localhost:8000
}

日志配置¶

example.com {
    root * /var/www/html

    log {
        output file /var/log/caddy/example.com.log {
            roll_size 100mb
            roll_keep 10
        }
        format json
    }

    file_server
}

完整配置示例¶

企业官网¶

example.com {
    root * /var/www/website

    # 压缩
    encode gzip zstd

    # 静态资源长期缓存
    @assets path /assets/* /js/* /css/* /images/* /fonts/*
    header @assets Cache-Control "public, max-age=31536000, immutable"

    # HTML 短期缓存
    @html path *.html
    header @html Cache-Control "public, max-age=3600"

    # 禁止访问隐藏文件
    @hidden path /.git/* /.env /.*
    respond @hidden "Not Found" 404

    # 日志
    log {
        output file /var/log/caddy/example.com.log
    }

    file_server
}

文件下载站¶

downloads.example.com {
    root * /var/www/downloads

    # 启用目录浏览
    file_server browse {
        template .html
    }

    # 下载响应头
    @download path *.zip *.tar.gz *.pdf
    header @download Content-Disposition "attachment"

    # 日志
    log {
        output file /var/log/caddy/downloads.log
    }
}

文档站点¶

docs.example.com {
    root * /var/www/docs

    # SPA 支持
    try_files {path} /index.html

    # 缓存策略
    @html path *.html
    header @html Cache-Control "no-cache"

    @static path *.js *.css *.png *.jpg *.svg
    header @static Cache-Control "public, max-age=31536000"

    encode gzip
    file_server
}

性能优化¶

连接设置¶

{
    # 全局选项
    servers {
        protocols h1 h2 h3
        max_header_size 16KB
    }
}

example.com {
    root * /var/www/html
    file_server
}

大文件优化¶

files.example.com {
    root * /var/www/files

    # 大文件传输优化
    file_server {
        disable_canonical_uris
    }
}

小结¶

本章介绍了 Caddy 静态文件服务的核心功能：

基本文件服务配置简单
支持目录浏览
灵活的缓存控制
SPA 应用支持
多站点和子域名配置

下一章将详细介绍自动 HTTPS 功能。