这篇写给所有把静态文件推到托管平台的人——个人博客、文档站、前端单页应用、小程序包都算:命令显示部署成功,线上却不是你要的那一版。下面这张表按角色列出你能带走什么、从哪节开始读。
| 读者 | 带走什么 | 拿它做什么 | 从哪节开始读 |
|---|---|---|---|
| 第一次给站点接自动发布的人 | 三层校验的顺序与判据 | 照着第 3~5 节写进发布脚本 | 3 → 5 |
| 已经遇到「发布成功但线上没变」的人 | 症状到层的对应表 | 用第 6 节的表从上传层往上查 | 1 → 6 |
| 负责值班与上线核对的人 | 一张可打印的判定表 | 贴进上线检查清单,逐行打勾 | 6 |
只在本机看效果、不往线上发布的人不必读。
约 12 分钟读完;需要你会用命令行发一次 HTTP 请求;不知道内容分发网络是什么也能跟。
部署命令的退出码只覆盖「文件送出去了」这一小段。文件到了平台之后,还要经过目录映射和缓存两层,才变成访客看到的页面;任何一层掉链子,命令仍然显示成功。这篇把上线前的判断拆成三层校验,每层给一个能执行的检查、一个通过标准,以及跳过它会出现什么症状。先看概览:
| 节 | 讲什么 | 解决什么问题 |
|---|---|---|
| 1 | 成功信号为什么不可信 | 先知道失败藏在哪三层 |
| 2 | 环境准备与最小示例 | 用几条命令先看到「本地有、线上没有」 |
| 3 | 第一层:文件数 | 上传中断、目录传错 |
| 4 | 第二层:目录可访问 | 路径映射、尾斜杠、大小写 |
| 5 | 第三层:内容一致 | 缓存、旧产物 |
| 6 | 可打印判定表 | 值班时逐行核对 |
| 7 | 坑表 | 六个常见误判 |
先解释「部署」在这个场景里指什么:把本地构建产物目录(通常叫 dist,里面是一堆 html、css、js、图片)逐个文件传到托管平台,平台按路径对外提供访问。托管平台可以是对象存储(存放文件的云服务)、静态托管服务,或者带自动部署的代码托管平台。
下面四种症状来自一次真实发布(页面数与检查项数按你的站点会不同,判断方法一样)。
这四种症状看起来无关,其实都卡在同一个位置:命令只证明了第一段。下面这张示意图是一条发布链从本机到访客经过的三层,后面每一节对应一层。
本机 dist/ ← 你真正要发布的东西
│ ① 上传:文件数、路径、大小写、是否被覆盖
▼
平台上的文件目录 ← ② 目录映射:/blog/a/ 指向 /blog/a/index.html
│ ③ 缓存:平台或浏览器还留着上一版
▼
访客看到的页面
为什么必须解决:404 会被搜索引擎记成坏链接;旧页面会让访客以为改动没生效;等有人反馈再回滚,成本比上线前多跑三条命令高得多。
后面的检查只需要 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
跑完你会看到三样东西:本地页面数、两个指纹是否相同、三个路径的状态码。三者任一不对,就对应下面三层中的一层。
「内容指纹」是把文件内容算成一串固定长度的字符:内容变一个字节,结果就不同,用来判断两份内容是不是同一份。
这一层只回答一个问题:该传的文件,是不是都到了平台?
要检查什么:本地产物里的页面数、平台文件列表里的页面数、站点地图里的链接数。三个数两两相等才算通过。
为什么这层能挡住:上传中断、传错目录、漏传新增目录,都会让数量先对不上。数量是最便宜、最先能查的信号。
跳过会出什么事:平台只收到一部分文件,首页照样能打开,看起来正常;只有点进某一篇才 404。这正是「站点地图里有、点开却是 404」最常见的成因之一——生成页面时读的那份数据没有写进去,页面根本没生成,数量从一开始就少。
下面的命令分三路数数:本地页面、平台文件、站点地图条数。
# 本地页面数
find dist -name index.html | wc -l
# 平台侧文件数:用平台命令行工具或控制台的文件列表统计
# 站点地图条数(每个 <loc> 一行)
grep -c '<loc>' dist/sitemap.xml
三个数不等,先修数量,不要往下走。
这一层回答:路径映射对不对。
先交代一个领域约定:托管平台通常把「目录」映射到该目录下的默认首页文件(例如 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
跑完没有任何输出,才算这一层通过。输出的每一行都是一个映射问题,先修映射,不要用重定向掩盖——重定向会让地址栏变化,分享出去的链接和搜索引擎记录的地址变成两个。
这一层回答:访客拿到的,是不是这一版。
要检查什么:抽若干页,把线上正文与本地文件比对。内容没被平台改写过时,直接比指纹;平台会注入统计脚本时,比一个稳定特征(标题、正文字数、首段前 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,旧产物就发不出去。修改时间不是完美指标(重新检出代码也会更新它),但它能拦住最常见的一种:昨天构建、今天发布。
下面这段是整条发布链的骨架,共 8 步:第 2 步准备比对基准,第 35 步分别对应三层,第 68 步是缓存与结论。
1 │ 前提 → 构建已完成,产物目录比源码新(否则先重建)
2 │ 发布前 → 算本地页面数与每页的内容特征(标题 + 正文字数 + 指纹)
3 │ 上传 → 记录成功文件数;与本地数量不等 → 失败,不往下走
4 │ 映射 → 根 / 列表 / 详情 / 深层 / 大小写各请求一次,非 200 → 失败并列出路径
5 │ 内容 → 抽 5~10 页,把线上特征与本地特征逐个比对
6 │ 不一致且刚发布过 → 刷新这些页的缓存,等 30~60 秒
7 │ 再比对一次 → 仍不一致 → 失败,打印页面地址与两边特征
8 │ 三层全过 → 才打印「发布成功」,并把三个数量写进日志
上线前把下面这张表贴进值班文档,每行都要有实际输出,不靠记忆:
| 层 | 检查什么 | 通过标准 | 失败先看哪里 | 典型症状 |
|---|---|---|---|---|
| ① 上传 | 本地页面数、平台文件数、站点地图条数 | 三个数相等 | 发布脚本的失败收集、目标目录 | 站点地图有链接,点开 404 |
| ② 映射 | 五种路径形态各请求一次 | 全部返回 200 | 平台的目录规则、默认首页、大小写 | 只有首页能开 |
| ③ 内容 | 抽样页的线上特征与本地特征 | 逐页相同 | 构建时间、缓存刷新 | 有人看到新页、有人看到旧页 |
| ③ 前置 | 产物时间与源码时间 | 产物不早于源码 | 是否用了跳过构建 | 发布成功,线上仍是昨天 |
使用顺序是从上往下:上一层不过,下一层的输出没有意义。
下面按「是什么 → 为什么是坑 → 怎么解决 → 为什么能解决」列出,每条都标了会遇到的场景。
| 坑是什么 | 为什么是坑 | 如何解决 | 为什么能解决 |
|---|---|---|---|
| 把部署命令返回 0 当成发布完成(场景:第一次接自动发布) | 命令只覆盖上传动作,映射与缓存还没验证 | 三层校验全过才打印成功 | 判断标准覆盖了从本机到访客的整条链 |
| 只请求首页(场景:手测或写检查脚本) | 首页往往被平台特殊处理,其他路径才暴露映射问题 | 按路径形态各抽一个 | 覆盖默认首页、尾斜杠、大小写三类规则 |
| 用重定向兜底 404(场景:平台不支持目录映射) | 地址栏变化,分享链接与搜索记录出现两个地址 | 修目录映射,或生成带完整文件名的链接 | 访客始终停在同一个地址 |
| 跳过构建后直接发布(场景:构建失败重跑省时间) | 产物可能早于源码,发的不是这一版 | 发布前比较源码与产物时间 | 拦住「昨天构建、今天发布」 |
| 对所有页面逐字节比较(场景:平台会注入统计脚本) | 平台改写内容后永远不相等,检查变成噪声 | 比稳定特征,或只对不被改写的文件比指纹 | 判断标准对准「访客能不能看到这一版」 |
| 检查只跑开发服务器(场景:新增只靠浏览器渲染的内容) | 开发服务器有兜底与热更新,产物里可能没有 | 断言对象改成产物文件与线上地址 | 产物和线上才是访客真正拿到的东西 |
这套校验现在做不到三件事:
在你要发布的站点上跑一遍第 2 节那三条命令,把本地页面数、站点地图条数、一个路径的状态码写在纸上。三个数或状态码有一个不对,就先修那一层,别急着改发布脚本。
这些内容来自一个真实站点连续多次发布事故的复盘:每次「部署显示成功、线上却没变」都追到上传、目录映射或缓存某一层,最后把三层检查写成脚本。文中的文件数、状态码与检查项都是当时实测的结果。