部署显示成功,线上却没变:三层校验把假成功挡在上线前 | 杨元超的世界

读者是谁

这篇写给所有把静态文件推到托管平台的人——个人博客、文档站、前端单页应用、小程序包都算:命令显示部署成功,线上却不是你要的那一版。下面这张表按角色列出你能带走什么、从哪节开始读。

读者 带走什么 拿它做什么 从哪节开始读
第一次给站点接自动发布的人 三层校验的顺序与判据 照着第 3~5 节写进发布脚本 3 → 5
已经遇到「发布成功但线上没变」的人 症状到层的对应表 用第 6 节的表从上传层往上查 1 → 6
负责值班与上线核对的人 一张可打印的判定表 贴进上线检查清单,逐行打勾 6

只在本机看效果、不往线上发布的人不必读。

约 12 分钟读完;需要你会用命令行发一次 HTTP 请求;不知道内容分发网络是什么也能跟。

0 本文讲什么

部署命令的退出码只覆盖「文件送出去了」这一小段。文件到了平台之后,还要经过目录映射和缓存两层,才变成访客看到的页面;任何一层掉链子,命令仍然显示成功。这篇把上线前的判断拆成三层校验,每层给一个能执行的检查、一个通过标准,以及跳过它会出现什么症状。先看概览:

节 讲什么 解决什么问题
1 成功信号为什么不可信 先知道失败藏在哪三层
2 环境准备与最小示例 用几条命令先看到「本地有、线上没有」
3 第一层:文件数 上传中断、目录传错
4 第二层:目录可访问 路径映射、尾斜杠、大小写
5 第三层:内容一致 缓存、旧产物
6 可打印判定表 值班时逐行核对
7 坑表 六个常见误判

1 先说清上下文:成功信号只覆盖第一段

先解释「部署」在这个场景里指什么:把本地构建产物目录(通常叫 dist,里面是一堆 html、css、js、图片)逐个文件传到托管平台,平台按路径对外提供访问。托管平台可以是对象存储(存放文件的云服务)、静态托管服务,或者带自动部署的代码托管平台。

下面四种症状来自一次真实发布(页面数与检查项数按你的站点会不同,判断方法一样)。

这四种症状看起来无关,其实都卡在同一个位置:命令只证明了第一段。下面这张示意图是一条发布链从本机到访客经过的三层,后面每一节对应一层。

本机 dist/                     ← 你真正要发布的东西
  │ ① 上传:文件数、路径、大小写、是否被覆盖
  ▼
平台上的文件目录               ← ② 目录映射:/blog/a/ 指向 /blog/a/index.html
  │ ③ 缓存:平台或浏览器还留着上一版
  ▼
访客看到的页面

为什么必须解决:404 会被搜索引擎记成坏链接;旧页面会让访客以为改动没生效;等有人反馈再回滚,成本比上线前多跑三条命令高得多。

2 环境准备与最小示例

后面的检查只需要 Node 18 以上,加上系统自带的 curl 与 sha256sum(Windows 上用 Git Bash 或 Windows 的 Linux 子系统跑)。不用安装任何第三方依赖。

下面这段最小示例把三件事一次做完:数本地页面数、比较一个页面的本地与线上内容指纹、请求三种路径形态。把域名换成你的域名即可。

# 1) 本地到底生成了多少页
find dist/blog -name index.html | wc -l
# 2) 抽一页,比较本地与线上的内容指纹
sha256sum dist/blog/hello/index.html
curl -s https://example.com/blog/hello/ | sha256sum
# 3) 三种路径形态各请求一次,看状态码
for u in / /blog/ /blog/hello/; do
  printf '%s %s\n' "$(curl -s -o /dev/null -w '%{http_code}' https://example.com$u)" "$u"
done

跑完你会看到三样东西:本地页面数、两个指纹是否相同、三个路径的状态码。三者任一不对,就对应下面三层中的一层。

「内容指纹」是把文件内容算成一串固定长度的字符:内容变一个字节,结果就不同,用来判断两份内容是不是同一份。

3 第一层:文件数对得上

这一层只回答一个问题:该传的文件,是不是都到了平台?

要检查什么:本地产物里的页面数、平台文件列表里的页面数、站点地图里的链接数。三个数两两相等才算通过。

为什么这层能挡住:上传中断、传错目录、漏传新增目录,都会让数量先对不上。数量是最便宜、最先能查的信号。

跳过会出什么事:平台只收到一部分文件,首页照样能打开,看起来正常;只有点进某一篇才 404。这正是「站点地图里有、点开却是 404」最常见的成因之一——生成页面时读的那份数据没有写进去,页面根本没生成,数量从一开始就少。

下面的命令分三路数数:本地页面、平台文件、站点地图条数。

# 本地页面数
find dist -name index.html | wc -l
# 平台侧文件数:用平台命令行工具或控制台的文件列表统计
# 站点地图条数(每个 <loc> 一行)
grep -c '<loc>' dist/sitemap.xml

三个数不等,先修数量,不要往下走。

4 第二层:每个目录真的能访问

这一层回答:路径映射对不对。

先交代一个领域约定:托管平台通常把「目录」映射到该目录下的默认首页文件(例如 index.html)。所以 /blog/hello/ 能打开,靠的是平台把请求指到 /blog/hello/index.html。有的平台要求写全文件名,有的对结尾斜杠敏感,有的区分大小写。这正是「文件明明传上去了,请求还是 404」的来源。

要检查什么:不要只请求首页,按路径形态各抽一个——根、列表页、详情页、深层目录、带斜杠与不带斜杠、大小写变体。

为什么这层能挡住:上传成功但映射规则不匹配时,文件在平台里,访客仍然拿不到。

跳过会出什么事:只有首页返回 200,其他路径全 404;或者本机开发服务器正常(它有自己的兜底规则),线上不正常。

下面这段按五种路径形态各请求一次,非 200 就打印出来。

# 每种路径形态各请求一次;非 200 就打印出来
for u in / /blog/ /blog/hello/ /blog/hello/index.html /Blog/Hello/; do
  code=$(curl -s -o /dev/null -w '%{http_code}' "https://example.com$u")
  [ "$code" = 200 ] || echo "FAIL $code $u"
done

跑完没有任何输出,才算这一层通过。输出的每一行都是一个映射问题,先修映射,不要用重定向掩盖——重定向会让地址栏变化,分享出去的链接和搜索引擎记录的地址变成两个。

5 第三层:线上内容与本地一致

这一层回答:访客拿到的,是不是这一版。

要检查什么:抽若干页,把线上正文与本地文件比对。内容没被平台改写过时,直接比指纹;平台会注入统计脚本时,比一个稳定特征(标题、正文字数、首段前 20 个字)。

为什么这层能挡住:上传和映射都对了,缓存仍可能发上一版。缓存指平台把文件复制到各地节点、访客就近取;源站更新后,节点上的旧副本要等过期或被主动刷新才更新。

跳过会出什么事:发布后几分钟到几小时,一部分访客看到新页面、一部分看到旧页面;「我明明发了」和「我这边没变」同时成立,排查会绕很久。

处理顺序:先确认本地产物是新的(构建时间晚于源码修改时间),再上传,再比对;不一致就刷新缓存,等 30~60 秒再比对一次。仍不一致就失败,不要循环重试到天亮。

旧产物的判定可以零依赖做:下面这段比较源码目录与产物目录的最新修改时间,产物早于源码就退出 1。

// node freshness.cjs —— 在站点根目录跑
const fs = require('node:fs')
const path = require('node:path')

function newest(dir) {
  let t = 0
  for (const name of fs.readdirSync(dir)) {
    if (['node_modules', 'dist', '.git'].includes(name)) continue
    const p = path.join(dir, name)
    const st = fs.statSync(p)
    t = Math.max(t, st.isDirectory() ? newest(p) : st.mtimeMs)
  }
  return t
}

const src = fs.existsSync('src') ? newest('src') : 0
const distFile = 'dist/index.html'
const dist = fs.existsSync(distFile) ? fs.statSync(distFile).mtimeMs : 0
const ok = dist > 0 && dist >= src
console.log(`ok=${ok} src=${src ? new Date(src).toISOString() : '(无源码)'} dist=${dist ? new Date(dist).toISOString() : '(无 dist)'}`)
process.exit(ok ? 0 : 1)

把它放在「跳过构建」分支的最前面,ok=false 时退出码为 1,旧产物就发不出去。修改时间不是完美指标(重新检出代码也会更新它),但它能拦住最常见的一种:昨天构建、今天发布。

6 思路级伪代码:把三层串成一次发布

下面这段是整条发布链的骨架,共 8 步:第 2 步准备比对基准,第 35 步分别对应三层,第 68 步是缓存与结论。

1 │ 前提   → 构建已完成,产物目录比源码新(否则先重建)
2 │ 发布前 → 算本地页面数与每页的内容特征(标题 + 正文字数 + 指纹)
3 │ 上传   → 记录成功文件数;与本地数量不等 → 失败,不往下走
4 │ 映射   → 根 / 列表 / 详情 / 深层 / 大小写各请求一次,非 200 → 失败并列出路径
5 │ 内容   → 抽 5~10 页,把线上特征与本地特征逐个比对
6 │ 不一致且刚发布过 → 刷新这些页的缓存,等 30~60 秒
7 │ 再比对一次 → 仍不一致 → 失败,打印页面地址与两边特征
8 │ 三层全过 → 才打印「发布成功」,并把三个数量写进日志

7 那张可打印的判定表

上线前把下面这张表贴进值班文档,每行都要有实际输出,不靠记忆:

层 检查什么 通过标准 失败先看哪里 典型症状
① 上传 本地页面数、平台文件数、站点地图条数 三个数相等 发布脚本的失败收集、目标目录 站点地图有链接,点开 404
② 映射 五种路径形态各请求一次 全部返回 200 平台的目录规则、默认首页、大小写 只有首页能开
③ 内容 抽样页的线上特征与本地特征 逐页相同 构建时间、缓存刷新 有人看到新页、有人看到旧页
③ 前置 产物时间与源码时间 产物不早于源码 是否用了跳过构建 发布成功,线上仍是昨天

使用顺序是从上往下:上一层不过,下一层的输出没有意义。

坑表

下面按「是什么 → 为什么是坑 → 怎么解决 → 为什么能解决」列出,每条都标了会遇到的场景。

坑是什么 为什么是坑 如何解决 为什么能解决
把部署命令返回 0 当成发布完成(场景:第一次接自动发布) 命令只覆盖上传动作,映射与缓存还没验证 三层校验全过才打印成功 判断标准覆盖了从本机到访客的整条链
只请求首页(场景:手测或写检查脚本) 首页往往被平台特殊处理,其他路径才暴露映射问题 按路径形态各抽一个 覆盖默认首页、尾斜杠、大小写三类规则
用重定向兜底 404(场景:平台不支持目录映射) 地址栏变化,分享链接与搜索记录出现两个地址 修目录映射,或生成带完整文件名的链接 访客始终停在同一个地址
跳过构建后直接发布(场景:构建失败重跑省时间) 产物可能早于源码,发的不是这一版 发布前比较源码与产物时间 拦住「昨天构建、今天发布」
对所有页面逐字节比较(场景:平台会注入统计脚本) 平台改写内容后永远不相等,检查变成噪声 比稳定特征,或只对不被改写的文件比指纹 判断标准对准「访客能不能看到这一版」
检查只跑开发服务器(场景:新增只靠浏览器渲染的内容) 开发服务器有兜底与热更新,产物里可能没有 断言对象改成产物文件与线上地址 产物和线上才是访客真正拿到的东西

还能怎么改进

这套校验现在做不到三件事:

  1. 抽样而不是全量:页面多时只抽 5~10 页,中间某页坏了可能漏掉。演进方向是构建时生成一份「页面 + 指纹」清单,发布后逐条比对,失败只列差异。
  2. 没有自动回滚:三层失败只是停下,线上可能已经是半新半旧。演进方向是保留上一版产物与一个切换开关,失败时切回上一版。
  3. 依赖平台不改写内容:会注入脚本的平台只能比特征。演进方向是标出「平台允许改写的区域」,其余部分做严格比对。

你下一步能做什么

在你要发布的站点上跑一遍第 2 节那三条命令,把本地页面数、站点地图条数、一个路径的状态码写在纸上。三个数或状态码有一个不对,就先修那一层,别急着改发布脚本。

这些内容来自哪里

这些内容来自一个真实站点连续多次发布事故的复盘:每次「部署显示成功、线上却没变」都追到上传、目录映射或缓存某一层,最后把三层检查写成脚本。文中的文件数、状态码与检查项都是当时实测的结果。

相关文章