Static-Web · XB 现场笔记

Content-Type 应描述你实际发送的字节

Sun, 23 Aug 2026 00:00:00 +0000

静态服务器可能返回正确的字节，却带上错误的 Content-Type。某个浏览器里页面看起来或许还正常，但下载、样式表、订阅阅读器或安全策略会把同一响应理解成别的东西。公开响应头才是契约；文件名只是服务器配置的输入。

检查有代表性的格式

检查一份 HTML 文档、样式表、SVG、feed 与可下载脚本。包含响应头但丢弃正文：

for path in / /assets/site.css /favicon.svg /index.xml /downloads/check-http-headers.sh; do
 curl -sS -D - -o /dev/null "https://www.example.test$path" \
 | awk -v path="$path" '
 BEGIN { print "== " path }
 /^HTTP\// || tolower($1) == "content-type:" || tolower($1) == "x-content-type-options:" { print }
 '
done

期望的媒体类型因资源而异，但应该具体且稳定。HTML 通常应包含字符集。CSS 与 SVG 不应被当作泛型二进制数据提供服务。用于下载的 shell 脚本不应被声明为 HTML。

保持 nosniff 一致

X-Content-Type-Options: nosniff 请求支持它的浏览器在脚本与样式目标上尊重声明的类型，而不是猜测。它之所以有用，是因为不匹配会变成可见的失败，而不是因浏览器而异的解读。

该响应头并不能修复一个错误的类型。只有在同时有能证明声明值正确的资源清单时才启用它：

X-Content-Type-Options: nosniff

检查服务器映射

静态服务器通常根据扩展名推导类型。如果某个新扩展名被当作 application/octet-stream 提供服务，先判断这是否有意为之，再决定是否加入全局覆盖。一个窄映射比一条会改变所有响应的规则更容易复核。

在公开主机名上重复这些检查。CDN 或反向代理可能替换掉正确的源站响应头；而一个友好的错误页可能为后缀像 CSS 或 JavaScript 的路径返回 HTML。

来源

RFC 9110 — HTTP Semantics，表示元数据与 Content-Type，已核验 2026-08-23。
MDN: Content-Type，媒体类型与字符集示例，已核验 2026-08-23。
MDN: X-Content-Type-Options，nosniff 行为，已核验 2026-08-23。

通过切换完整目录发布静态网站

Sun, 23 Aug 2026 00:00:00 +0000

直接把新文件复制到活动的静态目录上，会造成一段访问者可能从一个版本拿到 HTML、从另一个版本拿到资源的时期。更安全的模式是：在活动树旁预置一棵完整的树，验证它，再改变目录名。

把所有发布目录放在同一文件系统上

当活动树、预置树与回滚树共享同一文件系统与父目录时，名字替换最强。先检查：

df -P /srv/www

在该父目录下创建唯一命名的中转目录。不要把未解析的变量或宽泛通配符当成删除目标来复用。

stage=$(mktemp -d /srv/www/site.new.XXXXXX)

填充并验证预置目录

把生成制品复制进空目录，然后检查代表性文件与期望的文件数：

tar -C public -cf - . | tar -C "$stage" -xf -

test -s "$stage/index.html"
test -s "$stage/404.html"
find "$stage" -type f | wc -l

当工具支持目录参数时，对预置路径运行链接与校验和检查。未通过验证的预置目录绝不能获得活动目录的名字。

用显式回滚路径切换名字

在第一次移动前解析每个路径：

live=/srv/www/site
stamp=$(date -u +%Y%m%dT%H%M%SZ)
rollback=/srv/www/site.old-$stamp

test -d "$live"
test -d "$stage"
test ! -e "$rollback"

mv "$live" "$rollback"
if mv "$stage" "$live"; then
 test -s "$live/index.html"
else
 mv "$rollback" "$live"
 exit 1
fi

这段序列在两个移动之间留下一个短窗口。对每次请求都对根的单一静态服务进程来说，该窗口通常很小但仍可观察。平台特定的 rename 或符号链接模式可以收紧切换；在依赖更强断言之前，请测试确切的文件系统与服务器行为。

验证公共边缘

切换之后，请求首页、一个深层路由、一个带指纹的资源与一个缺失路径。把公共字节与预置制品比较。在检查完成与观察窗口结束之前，保留回滚目录。

来源

POSIX rename()，名字替换语义，已核验 2026-08-23。
Linux rename(2)，文件系统与替换行为，已核验 2026-08-23。
GNU tar manual，归档创建与解包，已核验 2026-08-23。

安全响应头应描述实际页面

Sat, 22 Aug 2026 00:00:00 +0000

安全响应头不是安全代码的替代品，但它们让浏览器强制实施有用的边界。策略应描述实际被服务的页面，而不是从另一个项目复制来的泛型模板。

从资源图开始

如果站点只提供 HTML、本地样式表、一个 favicon、没有任何可执行 JavaScript，那么一条窄策略是可理解的：

Content-Security-Policy: default-src 'self'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'; object-src 'none'; script-src 'none'; style-src 'self'; img-src 'self' data:

script-src 'none' 只有在站点不需要可执行脚本时才是正确的选择。加入搜索、评论或统计标签会改变资源图，并应触发一次有意识的策略复核。

增加传输与嵌套保护

对仅 HTTPS 的站点，下列响应头是常见起点：

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=(), usb=()

只有当每个子域名都准备好提供 HTTPS 时才启用带 includeSubDomains 的 HSTS。响应头是与未来部署的契约，而不只是扫描器里的一个分数。

检查行为，而不只是存在

请求一个正常页面、一个缺失页面与一个静态资源。错误响应应携带与成功响应同样重要的安全响应头。还要确认压缩与缓存不会改变内容类型，也不会暴露内部路径。

本站的Caddy 示例只是一个起点，不是普适策略。请根据你自己的部署调整主机名、证书处理与应用路由。

来源

MDN: Content Security Policy guide，CSP 指令名称与语法，已核验 2026-08-22。
MDN: Strict-Transport-Security，HSTS 指令与部署注意事项，已核验 2026-08-22。
Caddy header 指令，响应头操作指令，已核验 2026-08-22。

发布在公共边缘一致之前不算完成

Sat, 22 Aug 2026 00:00:00 +0000

静态发布消除了应用运行时的复杂度，但不会消除生成目录与公共响应之间的边界。发布检查应同时覆盖两边。

从干净的制品开始

使用固定生成器构建到干净的目录。记录源码提交、生成器版本、输出文件列表，以及用户会下载的文件的校验和。一次干净的构建能捕获复制式部署可能会意外保留的陈旧文件。

make verify
find public -type f -print | sort

文件列表是证据，不是装饰。如果某条路由消失，diff 应能说明是该来源被移除，还是生成器未能产出它。

演练三类响应

请求一个 HTML 页面、一个静态资源与一个缺失路径。检查状态码、内容类型、缓存策略与安全头：

curl -fsS -D - -o /dev/null https://www.example.test/
curl -fsS -D - -o /dev/null https://www.example.test/downloads/check-http-headers.sh
curl -sS -D - -o /dev/null https://www.example.test/does-not-exist

第三条命令有意不用 -f：404 是预期结果，仍应被捕获。把公共正文与生成的 404.html 比较，并确认状态始终为 404。

让回滚保持简单

在新目录通过检查之前，不要删除上一个目录。回滚应选择一个已知良好目录，而不是在事故中凭记忆重新构造一个。发布检查清单与HTTP 响应头检查都刻意做得足够小，能在干净的 shell 里运行。

来源

RFC 9110 — HTTP Semantics，状态与表示语义，已核验 2026-08-22。
curl manual，响应检查选项，已核验 2026-08-22。
静态网站发布检查清单，本地配套资源。

静态服务器应有一个明确的根目录

Sat, 22 Aug 2026 00:00:00 +0000

静态部署最有用的属性是：运维人员不用读应用代码，就能回答"这条响应是哪个目录提供的？"。Caddy 的 root 与 file_server 指令直接提供了这个边界。

让根目录明确

一个最小的站点块可以贴近制品布局：

www.example.test {
 root * /srv/example-site
 encode zstd gzip

 header {
 -Server
 X-Content-Type-Options nosniff
 X-Frame-Options DENY
 Referrer-Policy strict-origin-when-cross-origin
 }

 file_server
}

该路径只是示例，不是该盲目粘贴的值。发布命令应发布一个完整目录、核验它，然后才把这个目录设为配置里的根。在旧的已知良好目录通过冒烟测试之前，保留它。

检查边缘，而不只是文件树

请求一个 HTML 页面、一个可下载的文本文件和一个缺失路径。把内容类型与状态码与本地制品比较。即使 404 页看起来很精致，若返回 200 仍是部署缺陷。

当 Caddy 管理 HTTPS 时，证书签发与 HTTP 到 HTTPS 的重定向都属于边缘行为。请从裸的 HTTP 监听器测试重定向，并从公共主机名读取证书名称。不要只凭进程健康就推断成功。

来源

Caddy file_server 指令，静态文件服务与根目录选择，已核验 2026-08-22。
Caddy header 指令，响应头配置，已核验 2026-08-22。
Caddy Automatic HTTPS，证书签发与 HTTPS 重定向，已核验 2026-08-22。
MDN: X-Frame-Options，防止被嵌套的选项，已核验 2026-08-22。

静态网站的发布检查清单

Sat, 22 Aug 2026 00:00:00 +0000

静态网站发布很简单，但简单并不免除发布检查的需要。有用的检查足够小，能在每次发布运行，也足够具体，能为真实的理由而失败。

构建干净的制品

使用固定版本的生成器，构建到一次性的输出目录：

hugo version
hugo --gc --minify --destination public

确切命令因项目而异，但关键属性是：输出能从受跟踪的源码复现。不要在构建之后手改生成的 HTML。

检查制品，而不只是源码

检视生成的树，确认期望的入口点存在：

test -s public/index.html
test -s public/404.html
test -s public/robots.txt
test -s public/sitemap.xml
find public -type f -print | sort

然后搜索意外的占位符、本地路径与仅开发用的主机：

rg -n 'localhost|127\.0\.0\.1|TODO|example\.com|/Users/' public --glob '!notes/a-release-checklist-for-a-static-site/**'

文章里有意保留的示例应用围栏明确标注为示例。链接里的主机名或私有路径通常是发布错误。

验证公共路由

在本地提供制品并请求访问者可达的路径：

hugo server --bind 127.0.0.1 --port 1313 --disableFastRender
curl -I http://127.0.0.1:1313/
curl -I http://127.0.0.1:1313/notes/
curl -I http://127.0.0.1:1313/resources/
curl -I http://127.0.0.1:1313/missing-page/

确认 404 路由在生产服务器上返回 404 状态。一个外观精美但状态 200 的错误页，仍然会破坏监控与缓存。

记录结果

在发布记录中保留源码提交、生成器版本与每个可下载资源的校验和。这样无需依赖记忆，就能把线上文件与产生它的源码进行比较。

这份检查清单的可下载版本在资源一节中。

来源

Hugo command reference，干净生产构建的生成器标志，已核验 2026-08-22。
curl manual，HTTP 验证与响应头检查选项，已核验 2026-08-22。
静态网站发布检查清单，可下载的配套资源。