404.html必须严格位于根目录且命名准确,无BOM、含正确YAML头(Jekyll)、返回真实404状态码,HTML需语义化含“404”文字,CSS内联、资源用绝对路径,链接纯HTML,JS仅DOMContentLoaded后执行。

404.html 文件名和位置必须严格匹配平台规则
GitHub Pages、Vercel、Netlify、Cloudflare Pages 这些静态托管服务,只识别根目录下名为 404.html 的文件——大小写、扩展名、路径都不能错。写成 404.htm、error-404.html、pages/404.html 或 404.HTML 都不会被接管。
常见踩坑点:
- Windows 记事本保存时可能加 BOM 头,导致 Git 提交后服务器无法识别;用 VS Code 或 Sublime 保存为 UTF-8 无 BOM
- Jekyll 用户需在
404.html开头加---\npermalink: /404.html\npublished: false\n---,否则会被当作普通页面渲染 - 确认 Git 已真正提交:运行
git ls-files | grep 404,输出应为404.html
服务器必须返回真实 404 状态码,不是“看起来像”
本地双击打开 404.html 是 200 OK,毫无意义。真正的 404 页面是服务器在找不到资源时,主动返回 404 Not Found 状态码 + 你的 HTML 内容。
验证方式(必须做):
立即学习“前端免费学习笔记(深入)”;
- 启动本地服务:
npx serve -s或python3 -m http.server 8000 - 访问一个不存在的路径,如
http://localhost:8000/xxx-abc123 - 打开 DevTools → Network → 找该请求 → 查看
Status是否为404 Not Found - 更准的方式:
curl -I http://localhost:8000/xxx-abc123,第一行必须是HTTP/1.1 404 Not Found
SPA 应用(React/Vue)特别容易翻车:location / { try_files $uri $uri/ /index.html; } 这类 fallback 规则会把所有 404 吞掉,返回 200 的 index.html。必须排除 /404.html 路径,或单独配置 error_page 404 /404.html。
HTML 结构里“404”三个字不能靠 JS 渲染或图片替代
搜索引擎和屏幕阅读器依赖语义化标签识别错误意图。<h1></h1> 必须直接包含 “404” 文字,比如 <h1>404 Not Found</h1> 或 <h1>页面未找到(404)</h1>。
这些写法都不可靠:
- 用 SVG 或 Canvas 绘制 “404” 字样
-
<h1 id="error-code"></h1>+document.getElementById('error-code').textContent = '404' - 用 CSS
::before伪元素插入文字
其他硬性要求:
-
<title></title>必须含 “404”,如<title>404 - 页面未找到</title> - 主内容用
<main></main>包裹,或加role="main" - 加
<meta name="robots" content="noindex">,防止被搜索引擎误收录
CSS 和跳转逻辑必须离线可用、零外部依赖
404 页面加载失败的最常见原因,就是等不到外部资源:CDN 挂了、Nginx 把 /css/style.css 也 fallback 到 index.html、或者相对路径在深层 URL 下失效。
正确做法:
- CSS 必须内联在
<style></style>标签里,控制在 1KB 以内;禁用<link rel="stylesheet"> - 所有图片用绝对根路径(如
/img/404-icon.svg)或 data URL,避免../assets/icon.png在/a/b/c下失效 - “返回首页”按钮必须是纯 HTML 链接:
<a href="/">← 返回首页</a>,不能是<button onclick="location.href='/'"></button> - 禁用
<meta http-equiv="refresh">和setTimeout(() => location.href = '/', 2000);想加动画跳转,必须用location.replace('/') + CSS animation,且动画结束后再触发
最后提醒:任何 JS 逻辑都必须放在 DOMContentLoaded 后执行,否则 DOM 未就绪就调用 document.querySelector 会静默失败。而最稳妥的底线是——没有 JS,页面也得能看清错误、点开链接、顺利离开。



















