部署至Azure存储静态网站的React应用非根路由报内容不存在错误

核心原因 #

React单页应用（SPA）的路由逻辑在客户端浏览器中处理，当直接访问/car/eleanor这类非根路径时，Azure存储会尝试在$web容器中查找对应路径的物理文件（比如car/eleanor.html），找不到就返回404错误。必须让Azure把所有非根路由请求转发到index.html，由React路由接管后续处理。

正确解决方案步骤 #

1. 配置Azure存储静态网站的错误页面 #

这是官方推荐的标准方案，无需额外配置文件，直接在Azure门户操作：

• 进入目标存储账户，找到「静态网站」选项
• 在「错误文档路径」输入框中填写 /index.html
• 点击「保存」，等待配置生效（通常几秒到几分钟）

2. 验证配置效果 #

• 直接访问/car/eleanor这类非根路由，此时Azure会返回index.html，React路由将正确渲染对应页面
• 若仍有问题，清除浏览器缓存后重试（浏览器可能缓存了之前的404响应）

3. CDN/FrontDoor场景的额外配置 #

如果配置了CDN或FrontDoor，需确保路由规则允许将所有路径请求转发到存储静态网站端点，同时避免缓存错误响应：

• 在CDN/FrontDoor的规则中，添加路径匹配规则，将所有请求路径（/*）转发到存储静态网站的主端点
• 配置缓存规则，禁止缓存错误响应（尤其是404），避免旧的错误响应被长期缓存

关于之前无效配置的说明 #

• web.config：这是IIS服务器的配置文件，Azure存储静态网站不基于IIS运行，因此该文件无效
• staticwebapp.config.json：这是Azure Static Web Apps服务的专属配置文件，而你使用的是存储账户启用的静态网站，并非Azure Static Web Apps服务，所以该文件不会被识别

额外注意事项 #

• 确保React应用使用BrowserRouter（而非HashRouter），HashRouter会在URL中添加#符号，虽能避免404但URL不够美观
• 部署前确认build文件夹中index.html引用的静态资源路径正确（可通过在package.json中配置homepage或使用相对路径实现）

内容的提问来源于stack exchange，提问作者Piotrek