404.html必须严格位于根目录、文件名全小写且无BOM,服务器需返回真实404状态码;HTML须含语义化404、可访问导航及JS降级方案,确保无障碍与SEO合规。

404.html 文件名和位置必须严格匹配平台要求
GitHub Pages、Netlify、Vercel、Cloudflare Pages 这些静态托管服务,只识别根目录下名为 404.html 的文件——大小写敏感、不能带扩展名变体(如 404.htm 或 error-404.html),也不能放在子目录里。
常见失败现象:你写了页面、也上传了,但访问 /nonexistent 时仍看到平台默认灰页。原因往往是:
- 文件名实际是
404.HTML(Windows 记事本可能自动大写)或带 BOM 字节 - Git 没真正提交:
git ls-files | grep 404看是否在索引中 - Jekyll 用户没加 front matter:
---\npermalink: /404.html\npublished: false\n---
服务器必须返回真实 404 状态码,不能跳转
光有 404.html 文件完全没用。关键在于:当请求一个不存在的路径时,响应头里必须包含 Status: 404 Not Found,且响应体是你写的 HTML —— 不是 302 重定向过去,更不能悄悄变成 200 OK。
验证方式:本地用 npx serve 启服务,打开浏览器 DevTools → Network → 访问一个无效路径 → 查看 Response Headers 中的 Status 值。
立即学习“前端免费学习笔记(深入)”;
各环境典型配置:
- Netlify:
_redirects文件写/* /404.html 404;或netlify.toml中配[[redirects]] from = "/*" to = "/404.html" status = 404 - Nginx:
error_page 404 /404.html;,并确保location = /404.html存在且不被 rewrite 覆盖 - SPA 应用(React/Vue):
try_files $uri $uri/ /index.html;这类 fallback 规则会吞掉所有 404,必须排除/404.html路径
HTML 结构里必须显式出现“404”文字,且用语义化标签
搜索引擎和屏幕阅读器靠结构识别这是错误页。<h1>404</h1> 不是可选项,而是硬性要求——不能用图片、SVG 文本、CSS 伪元素或 JS 动态插入来替代。
基础骨架应包含:
-
<main></main>包裹核心内容,避免用<div> 模拟<li> <code><h1>404 Not Found</h1>或<h1>404 页面未找到</h1>(含“404”字样) - 导航按钮全部用
<a href="/">回到首页</a>,不要用<button onclick="location.href=..."></button> - 若需“回到上一页”,得先 JS 判断
document.referrer是否同域有效,再渲染链接 - 搜索框要带
<form action="/search"></form>和<input type="submit">,不能只靠 JS 绑定事件 - 背景图、字体、图标尽量内联或使用相对路径,避免 CDN 失效导致空白
- 文字对比度 ≥ 4.5:1(可用 WebAIM Contrast Checker 验证)
- 避免把“即将跳转”逻辑藏在 JS 里;无障碍要求必须有可见文案 + 可点击按钮
所有交互必须降级可用,禁用 JS 时仍能工作
用户可能禁用 JavaScript,或 Service Worker 缓存导致 JS 未加载。任何依赖 JS 的跳转、动画、音频播放,都必须有纯 HTML 备选方案。
例如:
最易被忽略的一点:很多开发者花时间做 Canvas 粒子动画或 Audio 提示音,却忘了检查 document.referrer 是否真的可读、<a></a> 链接是否用了绝对 URL 导致跨域失效、以及 404.html 是否被 SPA 的路由规则意外 fallback 成了 200。状态码不对,其他全白搭。



















