部署后页面 404

一句话：网站部署成功但访问某些页面报404，常见原因是路由配置不对、构建输出路径不匹配，或者是单页应用刷新页面路由处理不当。

它是什么

本地开发能正常访问的页面，部署到线上却404，通常不是内容真的丢了，而是服务器/托管平台不知道该怎么把这个URL对应到正确的文件——尤其是前端单页应用（SPA）用了前端路由，服务器需要额外配置把所有路径都指向index.html。

适合干什么

• 单页应用部署后刷新非首页路径报404
• 静态网站部署路径和实际访问路径不一致

不适合干什么

• 页面本身内容真的不存在（那是内容问题，不是部署配置问题）

普通人怎么用

如果是React/Vue这类单页应用，检查托管平台有没有配置"所有路径都返回index.html"（不同平台叫法不同，如Vercel的rewrites、Netlify的_redirects文件）；确认部署的构建输出目录设置正确。

进阶用户怎么用

区分是Nginx/服务器层面的路由问题还是前端路由（如React Router）的history模式配置问题；用hash路由（URL带#号）可以规避大部分服务器配置问题，但会牺牲URL的美观度和部分SEO效果。

常见误区

• 以为404是代码问题，实际大多数时候是部署平台/服务器的路由转发配置没做对
• 本地开发用 npm run dev 一切正常，就以为生产环境构建也一定没问题，实际开发服务器和生产构建的路由处理方式可能不同

和相似工具的区别

• 和 server-404（服务器层面配置错误）关系密切：前端SPA的404问题本质也是服务器不知道怎么处理这个路径，解法是让服务器对不存在的静态文件路径统一返回index.html

入门步骤

• 确认是首页正常、其他路径404，还是所有页面都404
• 检查托管平台的路由重写/rewrites配置
• 确认构建输出目录和平台配置的目录一致