一、「静态资源 404」为什么比页面 404 更危险
页面返回 404,用户看得见,会立刻反馈,改起来也清楚。静态资源返回 404 则完全不同:页面照样是 200,用户看到的是一张碎图、一个没样式的排版、一个点了没反应的按钮。它不会触发任何页面级告警,也不会出现在访问统计的异常里,唯一的痕迹是访问日志中那些状态码为 404 的 js、css、woff2、webp 请求,而被抓走的往往正是「新发布的那个版本」。
我在自己的站上做过一次统计,连续七天,静态资源 404 的数量占全部 404 的七成以上,其中一半以上来自同一次发版。原因很简单:模板里引用的是带指纹的新文件名,而文件同步脚本漏掉了图片目录;页面 HTML 更新了,图片还是旧的。这类问题的共同特征是发生在上线后的几分钟内,且只影响一部分用户,因为 CDN 边缘节点还没全部刷新。
更隐蔽的一种是「软 404」。服务器对不存在的静态文件返回 200,内容是一个自定义的错误页 HTML。浏览器会把这段 HTML 当成图片或脚本解析:当图片时显示碎图,当脚本时抛语法错误。这种问题在日志里完全看不到,因为状态码是干净的 200。判断方法是看响应体的内容类型和长度:一个本该是图片的响应,Content-Type 却是 text/html,就一定有问题。
# 一条命令同时看状态码、类型与长度,识别软 404
for u in /static/app.js /static/logo.webp /static/font.woff2; do
curl -sI "https://example.com$u" | awk -v u="$u" 'BEGIN{printf "%s ", u}
/^HTTP/{printf "%s ", $2}
/^[Cc]ontent-[Tt]ype/{printf "%s ", $2}
/^[Cc]ontent-[Ll]ength/{printf "%s", $2} END{print ""}'
done这张表如果出现「200 text/html 4213」这样的行,说明服务器把一个 HTML 错误页当静态资源返回了,需要修的是 nginx 的 error_page 与静态目录的匹配顺序,而不是去补文件。
二、从访问日志里把静态资源 404 捞出来
排查的第一步是拿到数据,而不是凭印象去点页面。访问日志默认格式里就有状态码和请求路径,只要能按扩展名过滤,就能得到一份清单。关键是过滤条件要覆盖所有静态类型,并且排除掉那些正常的、本来就不该存在的探测请求。
我把日志分析分成三步。第一步按扩展名与状态码聚合成清单,先看「哪些文件被大量请求且 404」,这通常指向真正的引用缺失。第二步按来源页面聚类,同一批 404 集中出现在一个 Referer 上,说明是某个模板的问题。第三步按时间看分布,如果某个时间点之后突然出现,那就是一次发版引入的。
# 第一步:近一天静态资源 404 清单,按次数排序
awk '$9==404 && $7 ~ /\.(js|css|png|jpe?g|webp|svg|woff2?|ico)$/ {print $7}' \
/var/log/nginx/access.log | sort | uniq -c | sort -rn | head -30第二步的聚合需要日志格式里有 Referer 字段。标准的 combined 格式里它排在倒数第二位,但各个面板默认配置不同,动之前先用 head 看一眼实际字段顺序,别凭记忆按下标取。
# 第二步:同一来源页面下,404 的资源分布
awk '$9==404 && $7 ~ /\.(js|css|png|webp)$/ {print $11}' \
/var/log/nginx/access.log | sort | uniq -c | sort -rn | head -20如果日志量很大,第一条命令会跑很久,可以只取末尾若干行,或者按小时分片处理。我习惯先处理最近两小时,因为静态资源 404 的时效性很强:发现得早,改一行模板或补一次同步就完事;发现得晚,搜索引擎已经抓到了失效的图片,页面快照里会留下一堆碎图。
三、四类成因,按出现频率排序
把清单拿到手之后,成因基本可以归到四类,每一类有不同的验证方法。
第一类是引用写错,主要是路径和大小写。本地开发在 macOS 上,文件系统默认大小写不敏感,Logo.webp 和 logo.webp 都能访问;上线到 Linux 后大小写敏感,一半的引用立刻失效。这类问题在日志里的特征是文件名只差大小写,解法是统一命名规范,并在构建时做一次引用校验。
第二类是文件没同步上去。模板更新了,图片目录没跟着传;或者同步脚本用了 exclude 规则,把某个新目录漏掉了。这类问题在日志里的特征是整批同一前缀的文件全部 404,解法是核对同步清单,并给同步脚本加一条「产物目录文件数比对」的自检。
第三类是缓存导致的版本错配。HTML 更新为引用带新指纹的文件,但 CDN 边缘还缓存着旧 HTML,或者反过来,文件已经更新但 HTML 还是旧的。这类问题在日志里的特征是 404 集中在发版后的几分钟内,且随时间快速下降。解法是上线顺序固定:先传静态文件,再刷 HTML 缓存,确认后再改模板。
第四类是外部资源失效。引用了别人的 CDN 上的库,对方改了路径或下线了。这类问题在日志里看不到,因为请求根本没打到你的服务器。要在浏览器控制台或前端错误监控里看。这类问题的正确解法不是去找新的 CDN,而是把关键依赖下载到自己的服务器上,减少外部依赖面。
# 快速确认某个文件在磁盘上是否存在、权限对不对
ls -l /var/www/site/static/ | head
# 确认 nginx 实际解析到哪个目录(比猜 root 指令快)
nginx -T 2>/dev/null | grep -A3 'server_name example.com' | head -20四、SRI 巡检:哈希不匹配会被静默拦下
子资源完整性校验是一把双保险:在 script 或 link 标签上声明哈希,浏览器下载后比对,不一致就拒绝执行。它的本意是防止第三方 CDN 被篡改,但副作用是「文件内容一变,页面就静默失效」。既没有报错弹窗,日志里也只是加载失败,很容易被当成随机故障。
因此凡是用 SRI 的资源,都必须把「文件变更」和「哈希更新」当成同一次提交。这在手工维护的站点上很容易漏,典型的漏法有三种:更新了库文件但忘了重算哈希;重算时用了 sha256 却仍写着 sha384;压缩与未压缩版本混用,哈希对的是未压缩文件,而引用的是压缩文件。
# 计算 SRI 哈希:算法必须与标签上声明的一致
openssl dgst -sha384 -binary app.min.js | openssl base64 -A
# 与标签比对
grep -o 'integrity="[^"]*"' index.html巡检的做法是把页面里所有带 integrity 属性的引用抽出来,逐个请求并重算哈希,比对结果。这个动作我放在每月一次的检查单里,脚本不超过二十行,但能挡住「某次升级后广告位脚本全部被拦」这类大事故。顺带一提,跨域资源要开 CORS 才能通过 SRI 校验,如果对方没返回 Access-Control-Allow-Origin,浏览器会直接拒绝,且错误信息容易误读成哈希不匹配。
还有一个判断要点:SRI 只对 script 和 link 有效,对 img、iframe 无效。有人试图用它保护图片,加了属性也不会生效。图片的完整性靠的是版本化文件名加长缓存,不是哈希校验。
五、把静态资源 404 变成可观测的指标
零散的排查只能解决已经发生的问题,要有长效机制,得把它变成一个能持续观察的数字:每小时静态资源 404 的请求数。这个数字平时应该是接近零的,一旦跃升就说明出了问题,比等用户反馈快得多。
实现方式最省事的是在日志轮转之后跑一个统计脚本,把结果写进一个时间序列文件或者直接推到监控系统。如果没有监控系统,一个每小时追加一行的文本文件也够用,看趋势时用脚本把最近二十四行打出来即可。
#!/bin/sh
# /usr/local/bin/static404.sh —— 每小时记一行
LOG=/var/log/nginx/access.log
N=$(awk '$9==404 && $7 ~ /\.(js|css|png|webp|woff2?)$/' "$LOG" | wc -l)
echo "$(date '+%Y-%m-%d %H:%M') $N" >> /var/log/static404.log
tail -n 48 /var/log/static404.log阈值不要定得太死。爬虫探测、扫描器会稳定贡献少量 404,一个正常站点每小时十几次是常态。我的经验阈值是每小时超过五十次就值得看一眼,超过两百次一定是事故。定阈值前先跑一周观察基线,别第一天就报警,否则必然被当成噪音关掉。
光有数字还不够,要能定位到具体的 URL。所以我在统计脚本里同时保留了一份「本小时 Top 5 失效路径」的输出,写在同一个日志文件里。出问题时不用再回头翻原始访问日志,直接看这一行就知道是哪个文件、哪个模板漏了东西。这个设计的成本几乎为零,但把平均修复时间从半小时压到几分钟。
六、上线流程里的三次检查
大多数静态资源 404 都能在上线流程里被挡住,前提是把检查点放在对的位置。我在发版流程里设了三道检查,分别对应「传之前」「传之后」「切流之后」。
传之前的检查是产物目录自检:统计各类文件数量、总字节数,与上一次发版对比,数量下降超过 20% 就中止。这条规则挡住了一次事故——某次构建脚本因为一个路径错误,只输出了 CSS 没有输出图片,数量对比立刻发现异常,没有上线。
# 发版前:与上次产物目录对比文件数
OLD=$(find /srv/releases/prev -type f | wc -l)
NEW=$(find /srv/releases/next -type f | wc -l)
echo "prev=$OLD next=$NEW"
[ "$NEW" -lt $(( OLD * 80 / 100 )) ] && { echo "ABORT: 文件数骤降"; exit 1; }传之后的检查是抽样请求:从新产物目录里随机取二十个文件名,逐个向线上发起请求,全部返回 200 才算通过。这一步能抓住权限问题、路径映射问题、同步漏目录问题,成本是二十次请求。
切流之后的检查是看日志里的 404 增量。发版时间点记下来,五分钟后统计这段时间的静态资源 404 数量,与发版前的同长度时间段对比。如果增量超过十,就要人工看一眼具体路径。这个检查要在切流后立即做,因为此时回滚的代价最小。
三道检查加起来不超过三分钟,能把绝大部分资源缺失挡在用户感知之前。剩下的漏网问题,交给每小时指标去发现。
七、缓存头配错,等于让你的巡检白做
顺着 404 排查往往能发现另一类相关的问题:那些没有 404 但行为不对的资源请求。最常见的是带指纹的文件被配了短缓存,导致每次访问都要回源校验;或者不带指纹的文件被配了一年长缓存,更新后用户半年看不到新版。这两个错误都不会产生 404,但都会让用户看到不该看到的版本。
判断规则只有一条:文件名里带内容哈希的,配长缓存;不带的,配短缓存或协商缓存。这条规则的执行力靠的是构建产物命名,不是运维配置。所以我在项目里要求所有静态资源在构建时统一加哈希,不允许手写路径引用固定文件名。
# 指纹文件一年缓存;无指纹文件只做协商缓存
location ~* \.[0-9a-f]{8,}\.(js|css|webp|woff2)$ {
expires 1y;
add_header Cache-Control "public, max-age=31536000, immutable";
}
location ~* \.(js|css|webp|woff2)$ {
expires 1h;
add_header Cache-Control "public, max-age=3600, must-revalidate";
}这里有个细节要注意:两个 location 同时能匹配一个请求时,正则 location 的执行顺序是按配置文件里的出现顺序,第一条匹配即停止。所以带指纹的规则必须写在前面,否则会被后面的规则覆盖。这个顺序错位在生产环境里很常见,症状是「明明配了长缓存,DevTools 里还是显示了 max-age=3600」。
八、把检查单固化下来
这套方法的价值不在于某一次排查,而在于它变成常规动作之后,静态资源 404 从「需要救火的事故」变成「几乎不发生的小事」。我的检查单最终收敛成五项,写进运维台账,每次发版和每个月各跑一次对应项。
发版时三项:产物目录文件数对比、抽样二十个文件请求、切流后五分钟 404 增量。每月一项:SRI 哈希全量巡检。每季度一项:全站资源引用校验,把所有模板里的引用抽出来,与产物目录做差集,找出引用了但不存在的文件,以及存在但没人引用的孤儿文件。孤儿文件不产生错误,但它们占磁盘、拖慢同步,也容易在未来的版本里被误删后才发现有引用。
# 季度巡检:引用集合与磁盘集合求差,找出失效引用与孤儿文件
grep -rhoE '(src|href)="/static/[^"]+"' templates/ | sed 's/.*="//;s/"//' | sort -u > /tmp/ref.txt
(cd /var/www/site && find static -type f | sed 's|^|/|' | sort -u) > /tmp/have.txt
echo "--- 引用但不存在(会导致 404)"; comm -23 /tmp/ref.txt /tmp/have.txt
echo "--- 存在但无人引用(孤儿)"; comm -13 /tmp/ref.txt /tmp/have.txt | head -20最后提醒一句:差集的结果里,动态拼接的路径会全部落进「引用但不存在」,比如模板里写成 /static/ + 变量。这类引用需要人工排除,不要直接照着清单删东西。判断方法是看这些路径里有没有变量特征,比如花括号或者连续的分隔符。排除掉之后剩下的才是真正需要处理的条目。
静态资源治理说到底是个工程习惯问题:让引用可校验、让产物可比对、让异常可观察。三件事都做到,就基本不会再出现「上线之后一片碎图」这种让人头皮发麻的场景了。