教程 · 编程上线
单页应用刷新就 404：把未知路径回退到 index.html
配置服务器或托管平台的路由回退规则，让前端路由的深链接刷新和直接访问都能正常打开。
前置：使用前端路由的单页应用，已部署到静态托管或自己的服务器。
材料：项目配置、托管平台文档、服务器配置、浏览器
材料：项目配置、托管平台文档、服务器配置、浏览器
步骤
1. 先确认是不是前端路由
从首页点进子页面正常、直接访问或刷新子页面 404，基本可以确定是前端路由没有回退；这是单页应用最常见的部署问题。
2. 配置回退到入口文件
在托管平台添加重写规则，把所有非静态资源请求指向 index.html；自己搭服务器就在 Nginx 里配 try_files。
3. 排除静态资源路径
回退规则要排除 js、css、图片等真实文件，否则资源请求也会返回 HTML，页面白屏且控制台报语法错误。
4. 测试深链接和刷新
直接粘贴一个二级路由地址打开，再按 F5 刷新，两种方式都要正常；只从首页点进去测试，永远发现不了这个问题。
5. 补一个真正的 404 页
对确实不存在的路径给出友好提示，而不是空白页；回退规则负责路由，404 页负责告诉用户走错了，别把 404 也回退成首页。
做完检查
- 直接访问二级路由能正常打开
- 刷新页面不出现 404
- 静态资源请求没有被回退成 HTML
常见错误
- 所有请求都回退，连 js 和图片也返回 HTML
- 只在首页点链接测试，不测直接访问
- 忽略带参数和锚点的链接
相关工具
同类教程
本地能跑线上 404：先查文件名大小写，再查构建产物
定位大小写、扩展名和路径别名导致的资源 404，用构建产物和大小写敏感环境验证修复。
查看 →密钥被打进了前端包：先分清公开变量和私密变量
识别构建时被内联到前端的变量，把密钥移到服务端并轮换已泄露的凭证。
查看 →换台电脑就构建失败：锁 Node 版本再清缓存重装
用版本文件和依赖锁把本地与 CI 的 Node 版本对齐，解决因版本差异导致的构建失败。
查看 →更新时间：2026-10-29 · 平台规则/软件版本会变；操作前保留原件，以实际页面为准。
跨库学习路径
按共同关键词匹配，不是随机推荐；从任务到提示词/教程/项目继续走。