404.html必须严格命名为小写、置于项目根目录,且服务器须返回真实HTTP 404状态码;GitHub Pages、Vercel、Netlify等平台仅识别该路径和命名,大小写敏感,禁止JS跳转或meta刷新伪装,SPA需排除404.html路径避免fallback覆盖。

404.html 文件名和位置必须严格匹配平台要求
几乎所有主流静态托管平台(GitHub Pages、Vercel、Netlify、Cloudflare Pages)只识别根目录下名为 404.html 的文件——不能是 404.htm、error-404.html、pages/404.html,也不能是 404.HTML(大小写敏感)。Windows 记事本保存时还可能偷偷加 BOM 头,导致 Git 提交后文件看似存在,实际被平台忽略。
验证是否生效的最直接方式:
– 运行 git ls-files | grep 404 确认它真在 Git 索引里
– 访问一个明显不存在的路径(如 /this-path-does-not-exist),用浏览器开发者工具 Network 面板看响应状态码是不是 404 Not Found,而不是 200 OK 或 302 Found
服务器必须返回真实 404 状态码,不是跳转过去
光有 404.html 文件毫无作用。关键在于:当资源不存在时,服务器要返回 HTTP 状态码 404,并把该文件内容作为响应体;而不是用 meta refresh 或 JS 跳转“伪装”成 404,更不能让 SPA 的 fallback 规则(比如 Nginx 的 try_files $uri $uri/ /index.html)把所有请求都兜底到 index.html,结果返回 200。
常见配置要点:
– Apache:ErrorDocument 404 /404.html(路径必须以 / 开头)
– Nginx:error_page 404 /404.html;,且需确保 location = /404.html 未被其他 rewrite 规则覆盖
– Jekyll 用户:要在 404.html 开头加 YAML front matter,否则会被当成普通页面渲染:
---\npermalink: /404.html\npublished: false\n---
立即学习“前端免费学习笔记(深入)”;
标签里必须出现 “404” 文字,不能靠图片或 JS 渲染
搜索引擎和屏幕阅读器依赖 HTML 结构判断页面语义。<h1>404 Not Found</h1> 不是装饰,而是硬性要求。用 SVG 绘制“404”、用 Canvas 动画生成、或靠 JS 插入文本,都会导致 SEO 丢失、无障碍失效——视障用户听到的是“网页标题”,而非“404 页面未找到”。
其他结构建议:
– 用 <main></main> 包裹核心提示文案与操作按钮
– 所有链接(首页、搜索、博客等)用标准 <a></a>,别用 onclick="location.href=..." 模拟
– 避免在 里加 meta http-equiv="refresh",这会让状态码变成 200
SPA 应用最容易踩的坑:路由 fallback 吞掉 404
React、Vue 等单页应用常配 location / { try_files $uri $uri/ /index.html; } 这类规则,目的是支持 History 模式路由。但它会把所有未命中静态文件的请求都交给 index.html,结果返回 200 + 你的 SPA 入口页,彻底掩盖真实 404。
修复方法很简单:
– Nginx 中,在 try_files 前排除 404.html:location = /404.html { }
– 或者更稳妥:把 404.html 放进 try_files 列表末尾:try_files $uri $uri/ /404.html;
– 注意:此时必须确保 error_page 404 不再启用,否则会冲突
真正难的不是写 HTML,而是让整个链路——从文件命名、Git 提交、服务器配置、到 SPA 路由逻辑——全部对齐 404 的语义本质:资源确实不存在,且服务器诚实地告诉你这一点。



















