Testing · XB 现场笔记

静态网站的发布检查清单

Thu, 30 Jul 2026 00:00:00 +0000

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

检查对象应是生成制品。干净输出不等于可复现；占位符搜索只是复核线索，真正的链接门禁应基于解析器。发布前服务确切制品，发布后比较两种语言的公共 GET 正文，并保存提交、生成器版本和下载校验和。

构建干净的制品

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

set -eu
hugo version
hugo --cleanDestinationDir --gc --minify --destination public

--gc 回收未使用的构建缓存资源，不会清理陈旧的已发布页面。--cleanDestinationDir 会移除目标目录中的陈旧文件，因此只能用于一次性制品目录，不能指向源码或其他数据所在的目录。把打印出的版本与项目固定版本比较；打印版本本身不会强制版本一致。记录构建输入并验证生成的制品。干净的目标目录不能证明逐字节可复现：时间戳与其他非确定性输入需要单独控制和比较。不要在构建之后手改生成的 HTML。

检查制品，而不只是源码

检视生成的树，确认期望的入口点存在。把下面的断言块作为独立 shell 脚本运行；任何必需文件缺失或为空时，都应在打印清单之前停止：

set -eu
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 -l 'localhost|127\.0\.0\.1|TODO|example\.com|/Users/' public --glob '*.html'

这只是复核线索，不是自动发布门禁：本清单这类示例本来就会命中，翻译页中也一样。这项仅检查 HTML 的扫描不会覆盖 XML 订阅或 JSON 搜索输出。rg 无匹配时退出 1，发生错误时退出 2。逐个复核列出的文件，区分围栏示例与有效链接或属性，并用基于解析器的链接检查作为真正门禁。公开链接中的私有路径属于发布错误。

验证公共路由

让隔离的类生产服务器直接指向这份制品，才能进行更可靠的发布前路由检查。Hugo 开发服务器会重新构建内容；下面是独立的源码预览，不能证明它服务的就是已经检查过的 public/ 字节。第一条命令在一个终端运行，其余请求在另一个终端运行：

hugo server --bind 127.0.0.1 --port 1313 --baseURL http://127.0.0.1:1313/ \
 --disableFastRender --disableLiveReload --renderToMemory
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/

HEAD 检查不比较正文。对待发布服务器再运行 GET，发布后将公共正文与制品比较，并检查两种语言。确认缺失路由在生产服务器上返回 404 状态。一个外观精美但状态 200 的错误页，仍然会破坏监控与缓存。

记录结果

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

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

来源

Hugo command reference，干净生产构建的生成器标志，已核验 2026-07-30。
curl manual，HTTP 验证与响应头检查选项，已核验 2026-07-30。
静态网站发布检查清单，可下载的配套资源。
Hugo server command reference，开发服务器重新构建、内存渲染与实时刷新控制，已核验 2026-10-15。

发布清单应点名每一个已发布的字节

Thu, 16 Jul 2026 00:00:00 +0000

静态制品是一个目录，而不是单个可执行文件。只记录源码提交或首页校验和会留下缺口：缺失的图片、陈旧别名或变化的下载可能悄悄留下来。传输前，应冻结制品并枚举其中每个常规文件。

测量前停止写入、拒绝符号链接和特殊文件，并将清单保存在制品树外。逐项校验发现缺失或变化的字节；重新生成并比较完整清单还可发现多余文件。对可信源端清单做哈希可得到紧凑标识，真实性与元数据仍需独立控制。

生成稳定的列表

从包含 public/ 的目录，在 Bash 中使用 GNU findutils 与 coreutils 运行以下命令。清单应保存在被测目录之外。发布只能包含目录和常规文件：先检查并拒绝符号链接或特殊文件，因为它们不在该清单的契约内。

set -euo pipefail
manifest="$PWD/release.sha256"
(
 cd public
 nonregular=$(find . ! -type d ! -type f -print -quit)
 test -z "$nonregular"
 find . -type f -print0 | LC_ALL=C sort -z | xargs -0 -r sha256sum --
) > "$manifest"
test -s "$manifest"

先排序文件名，再计算哈希。工具之间用 NUL 分隔路径，可保留空格、制表符与内嵌换行；GNU sha256sum 会在普通可校验输出中转义特殊文件名。不要用 awk '{print $2}' 解析该输出：文件名中可以合法包含空白。单独赋值会保留 find 失败时的退出状态；只检查其输出，可能把扫描失败误认成空结果。扫描或管道一旦失败，就应把清单视为不完整，不得发布。测量期间停止写入；这些命令不会创建文件系统快照。

传输后验证

在目标端的同一个可丢弃 Bash 会话中，按顺序运行后续片段，使路径变量与 set 选项保持生效。将清单与制品路径设为实际位置：

set -euo pipefail
manifest=/path/to/release.sha256
artifact=/srv/www/site.new
(
 cd "$artifact"
 sha256sum -c "$manifest"
)

检查列出的文件能发现缺失或改变的字节，却不能发现多余文件。因此按相同流程重新生成目标端清单，并比较完整记录：

observed=$(mktemp "${manifest}.observed.XXXXXX")
trap 'rm -f "$observed"' EXIT
(
 cd "$artifact"
 nonregular=$(find . ! -type d ! -type f -print -quit)
 test -z "$nonregular"
 find . -type f -print0 | LC_ALL=C sort -z | xargs -0 -r sha256sum --
) > "$observed"
diff -u "$manifest" "$observed"

没有差异且退出状态为零，表示常规文件的路径与哈希一致。多出一个陈旧文件也会使检查失败。临时输出位于制品之外，因此检查不会包含自身。空目录、权限、所有者与时间戳不在测量范围内；部署依赖这些属性时需另行验证。

为发布记录增加聚合摘要

对清单本身做哈希，得到紧凑的发布标识：

sha256sum "$manifest"

其含义依赖固定的规则：相对路径、排序区域、算法、工具格式，以及包含哪些元数据。将可信清单与源码提交、构建器版本一起保存。

不要把完整性等同于真实性

SHA-256 摘要一致，是字节一致的强实用证据，并不能证明作者身份。攻击者若能同时替换制品与清单，也能让检查通过。签名与可信分发是独立控制；只应校验通过预期可信渠道取得的清单。

来源

GNU Coreutils: sha2 utilities，校验和生成与验证；通过下列上游手册源码核对，已核验 2026-10-15。
GNU Coreutils 手册源码，非 tagged 校验和的转义、--check 与 NUL 分隔排序，已核验 2026-10-15。
sha256sum(1)，命令行为与输出格式，已核验 2026-07-16。
GNU Bash: Simple Command Expansion，纯赋值命令保留命令替换的退出状态，已核验 2026-10-18。

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

Thu, 09 Jul 2026 00:00:00 +0000

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

切换前后使用同一份制品。下载行对应文中的 public/downloads/check-http-headers.sh。cmp 比较前会解码受支持的内容编码；服务器转换需有明确比较规则。状态和响应头另行检查，并保留前一目录供主动回滚。

从干净的制品开始

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

set -eu
make verify
find public -type f -print | sort

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

演练三类响应

发布前，用预期服务器配置测试待发布制品。切换目录后，在公共边缘重复检查；探测仍在线的旧站不能验证新发布。请求一个 HTML 页面、一个静态资源与一个缺失路径。检查状态码、内容类型、缓存策略与安全头：

set -eu
curl --compressed -fsS -D page.headers -o page.body https://www.example.test/
curl --compressed -fsS -D asset.headers -o asset.body \
 https://www.example.test/downloads/check-http-headers.sh
curl --compressed -sS -D missing.headers -o missing.body \
 https://www.example.test/does-not-exist

cmp public/index.html page.body
cmp public/downloads/check-http-headers.sh asset.body
cmp public/404.html missing.body

把每个片段作为独立 shell 脚本运行，或放在可丢弃的 shell 会话中执行。set -eu 让这个顺序脚本在构建、传输或比较失败后停止，避免后面的成功命令掩盖先前失败。缺失路径的请求有意不用 -f：404 是预期结果，仍应被捕获。检查各响应头文件的最终状态：依次为 200、200、404；字节比较不会自动完成状态码检查。这里不跟随重定向。--compressed 在比较前解码受支持的内容编码；若服务器有意转换 HTML，需要另行说明比较规则。cmp 相等时不输出，有差异时返回非零。在 /zh/ 及其错误页上重复检查，不能直接假设两种语言一致。

让回滚保持简单

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

来源

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

范围请求应证明选中了哪些字节

Mon, 06 Jul 2026 00:00:00 +0000

范围请求让客户端请求表示的一部分。媒体播放器、可断点续传的下载工具与诊断客户端会用到它，但服务器如果错误地声明或返回范围，就可能产生静默损坏，而不是干净的失败。

保持表示与内容编码一致，同时核对区间、总大小与实际正文字节。忽略 Range 时，完整的 200 可以合法；续传需要合适的强验证器。

建立完整大小

选择至少 16 字节、测试期间不变的下载文件。在同一个一次性 shell 会话和临时工作目录中依次运行以下片段，保留 url 与 size。显式的 set -eu 会让顺序执行的传输与字节断言失败时停止；HTTP 状态与范围响应头仍需按下文人工核对：

set -eu
url=https://www.example.test/downloads/archive.tar.gz
curl -fsS -H 'Accept-Encoding: identity' -D full.headers -o full.body "$url"
size=$(wc -c < full.body)
test "$size" -ge 16
awk 'tolower($1) ~ /^(content-length:|content-encoding:|etag:|last-modified:|accept-ranges:)$/ { print }' full.headers

确认完整响应为 200，且没有意外的内容编码。这些命令请求 identity 表示，不做自动解压；字节范围针对所选的编码后表示，因此改变编码会使比较失效。Content-Length 可能缺失，所以用完整正文确定大小。

Accept-Ranges: bytes 是显式信号，但缺少这个头并不能证明范围请求不受支持。去实际请求一次。

请求一个已知区间

请求开头 16 字节，同时保留响应头与正文：

set -eu
curl -sS -D range.headers -o range.body \
 -H 'Accept-Encoding: identity' -H 'Range: bytes=0-15' "$url"

wc -c range.body
head -c 16 full.body > expected.body
cmp expected.body range.body
awk 'tolower($1) ~ /^(content-range:|content-length:|etag:)$/ || /^HTTP\// { print }' range.headers

成功的字节范围响应应使用 206 Partial Content。Content-Range 应指出 0-15 与完整表示长度，而正文应正好包含 16 个字节。

这里的字节比较专门检查部分正文。合法但大于 16 字节的完整 200 会使比较失败并停止当前 shell 会话；先查看已保存的响应头，再判断是否发生损坏。反过来，完整文件恰好为 16 字节时，即便返回 200 也可能通过 cmp，所以仍需核对状态码与 Content-Range。

测试一个不可能的区间

从完整字节数开始请求：大小为 N 的文件，最后一个有效偏移量是 N−1。与任意写一个大常量不同，这确实超出了已知表示：

set -eu
curl -sS -D - -o /dev/null \
 -H 'Accept-Encoding: identity' -H "Range: bytes=${size}-" "$url"

服务器用 416 Range Not Satisfiable 拒绝无法满足的字节范围时，应附带 Content-Range（例如 bytes */12345）报告当前大小。当服务器忽略 Range 时返回 200 也可能合法，但它必须返回完整表示，而不是一个标签错误的片段。

让验证器留在故事里

续传工具可以用 If-Range 配合强 ETag。不能使用弱 ETag；只有在没有 ETag、且日期符合强验证器条件时，才能使用 HTTP 日期。如果表示已改变，安全响应是完整的最新表示，而不是从两个版本拼接出的字节。在宣称某个下载"可续传"之前，先测试这一行为。

来源

RFC 9110 — HTTP Semantics，范围单位、部分响应与 Content-Range，已核验 2026-07-06。
curl manual，--range 与响应头选项，已核验 2026-07-06。

HEAD 应描述与 GET 相同的表示

Mon, 22 Jun 2026 00:00:00 +0000

HEAD 方法请求服务器对 GET 会返回的响应，但不会传输响应内容。它适合需要状态、验证器、类型或长度的检查，但前提是元数据与真实的 GET 路径保持一致。

比较 HEAD 与 GET 之前，先对齐 URL、请求头、发布版本与内容编码。允许省略的字段不能自动判为失败。应保留小 GET 的正文或校验和检查，因为看似合理的元数据不能证明有效载荷完好。

比较规范化后的响应头集合

Date 这类动态响应头会随请求不同而变化。只比较描述所选表示的那些字段：

url=https://www.example.test/downloads/manual.pdf

curl -sS -I "$url" > head.headers
curl -sS -D get.headers -o /dev/null "$url"

for file in head.headers get.headers; do
 printf '== %s\n' "$file"
 awk '
 /^HTTP\// ||
 tolower($1) ~ /^(content-type:|content-length:|content-encoding:|cache-control:|etag:|last-modified:|vary:)$/ { print }
 ' "$file"
done

在可丢弃的工作目录运行，因为两个头部文件会被覆盖。对齐 URL、请求头与发布版本；压缩协商也应纳入比较，给两个请求发送相同的 Accept-Encoding 值。

HEAD 应描述对应的 GET，但 RFC 9110 允许省略只有在生成内容时才能确定的字段。单独缺少 Content-Length 不代表失败；如果 HEAD 携带它，其值必须是对应 GET 内容的长度，不能因为 HEAD 没有正文就填零。比较时应统一内容编码，调查变化的验证器与类型，而不是要求两份头部逐字节相同。

不要把 HEAD 当作唯一的发布检查

服务器可能在文件缺失、不可读或被截断时仍合成看似合理的响应头。在冒烟测试里保留一个小的 GET 并核验其正文或校验和。HEAD 降低了传输成本，但并不能证明有效载荷存在。

显式检查重定向

不使用 --location 时，curl -I 报告第一个响应，适合测试重定向策略；使用 --location 时，会打印跟随过程中的多个响应头块，包括中间重定向与最终目标。请记录这条命令回答的是哪个问题：

curl -sS -I --max-redirs 0 https://old.example.test/manual
curl -sS -I --location https://old.example.test/manual

把方法相关的失败视为配置缺陷

一个对 GET 返回 200、对 HEAD 返回 405 或 404 的静态页面，通常暴露出代理或路由的不一致。应当修复方法处理，而不是教监控系统忽略它——除非端点契约刻意不允许 HEAD。

来源

RFC 9110 — HTTP Semantics，HEAD 方法语义，已核验 2026-10-15。
curl manual，--head、--include 与重定向选项，已核验 2026-10-15。