It supports these Zeabur extensions:

• _headers file
• _redirects file

docker build -t zeabur/caddy-static .
docker run -p 8080:8080 -v $(pwd)/examples/caddy:/usr/share/caddy -it zeabur/caddy-static

MAJOR=1 MINOR=0 PATCH=0 bash build.sh

The server listens on :8080 and serves files from /usr/share/caddy. It auto-detects whether the site is an SPA or an MPA based on the presence of /404.html in the site root.

Requests are matched in order:

1. Sensitive paths are blocked before any file lookup.
2. Asset requests are served as real files only.
3. Document requests are matched against:
   • The path as-is (e.g. /about.html)
   • The path with a .html suffix (e.g. /about → /about.html)
   • A directory index (e.g. /users/ → /users/index.html)
4. Document misses fall back according to SPA/MPA mode.

This avoids using file_server status 200 for SPA fallbacks. Caddy's file server uses http.ServeContent, which can correctly return 304 Not Modified for If-None-Match and 206 Partial Content for range requests. A forced status 200 wrapper would overwrite those status codes.

The route decides what to do with unmatched requests:

Asset requests — paths whose final segment ends with a non-.html/.htm extension (matched by \.[A-Za-z0-9]+$) always receive a plain-text 404 Not Found response. They never fall back to index.html or 404.html. This prevents broken <script> and <link> loads from silently serving HTML.

Document requests — everything else:

The SPA status-200 return is intentional: client-side routers need a 200 to bootstrap. It is produced by serving /index.html normally after an internal rewrite, not by forcing file_server status 200, so conditional requests can still return 304.

Requests matching /.git/*, /node_modules/*, /vendor/*, or /.venv/* are blocked and return 404 regardless of whether the files exist on disk.

Responses are compressed with gzip or zstd based on the client's Accept-Encoding header.

• /api/v1.2 (or any path whose final segment ends in a digit after a dot) — the asset regexp \.[A-Za-z0-9]+$ matches the trailing .2, so this is classified as an asset miss and returns a plain 404 rather than the SPA/MPA fallback. If your SPA routes contain dotted numeric segments in the final position, avoid this pattern.

• /FILE.HTML (uppercase extension) — Caddy's not path *.html *.htm matcher is case-insensitive on case-insensitive filesystems but may not be on Linux. Test your deployment if you serve mixed-case HTML paths.

The E2E tests require the zeabur/caddy-static Docker image. Build it first:

docker build -t zeabur/caddy-static .

Then run the full suite without the Go test cache:

go test -count=1 -v ./e2etest

A — Real file hits

B — Sensitive path blocking

C — SPA fallback (missing document → index.html + 200)

E — Missing asset → plain 404 (not SPA/MPA fallback)

All 20 paths return 404 with plain-text Not Found, Content-Type ≠ text/html, body ≠ SPA_INDEX:

/assets/missing.{js,mjs,css,css.map} · /img/missing.{png,jpg,svg,webp,avif,ico} · /fonts/missing.{woff2,woff,ttf} · /missing.{json,xml,txt,pdf,mp4,wasm,zip}

F — Asset/document classification boundary

G — URL and path edge cases

H — HTTP methods

I — Response headers

J — Regression (bugs fixed by the current Caddyfile)

A — Real file hits — identical to SPA A1–A14 (existing files always served directly).

B — Sensitive path blocking — identical to SPA B1–B8.

D — MPA fallback (missing document → 404.html + 404)

E — Missing asset — identical to SPA E (plain 404, body ≠ CUSTOM_404).

F — Asset/document boundary

Same classification logic as SPA. Document misses show CUSTOM_404 at 404; asset misses return plain 404 without CUSTOM_404.

G — URL and path edge cases

G3, G7, G9 same assertions as SPA. MPA-specific additions:

H — HTTP methods

I — Response headers

J — Regression