Ionic v5应用Azure静态部署因/home路由导致页面刷新失败

核心根因定位 #

• 首次部署时出现runtime.js加载400、“请求输入超出范围”报错，是因为未开启Blob静态托管能力，直接将资源上传到普通公开Blob容器时，服务端会对带内容hash后缀的长文件名静态资源触发参数合规校验，不符合普通容器的访问规则就会抛出越界类错误。
• 开启静态托管后刷新页面出现404，本质是Ionic v5 基于Angular的默认路由配置，和纯静态服务器的资源解析逻辑不匹配：
  • ng serve开发模式下，本地开发服务器默认开启SPA路由兜底能力：所有未匹配到真实文件的路径请求，都会被自动重定向回根路径的index.html，交由前端路由器处理路径跳转，因此访问带/home这类路由路径的地址时，无论怎么刷新都不会报错。
  • Azure静态Blob存储、本地默认启动的http-server，没有内置SPA兜底规则。当访问/home路径时，服务器会直接在存储容器内查找名为home的真实文件/文件夹，找不到就直接返回“内容不存在”的404错误。
• 旧版Ionic项目从未出现这类问题，是因为旧版默认采用Hash路由模式，所有页面跳转路径都带#标识（例如index.html#/home），静态服务器只会解析#符号前面的部分作为真实资源路径，永远不会把/home当成需要请求的真实文件。

可直接落地的修复方案 #

• 方案1：切换为Hash路由模式，完全适配静态托管逻辑
  • 打开项目内的src/app/app-routing.module.ts配置文件，在RouterModule.forRoot的传入参数中，追加{ useHash: true }配置项。
  • 重新执行ionic build生成最新的www文件夹构建产物，重新上传到存储容器即可。修改后所有路由路径都会变成带#的格式，静态服务器不会再对路由部分发起真实资源请求，彻底解决刷新404问题。
• 方案2：保留Path路由模式，配置Azure静态托管的SPA兜底规则
  • 进入Azure存储账户的静态网站配置页，找到*错误文档（404）*配置项，将返回值设置为index.html。
  • 配置完成后，所有未匹配到真实资源的404请求，都会被自动重定向返回根路径的index.html，应用加载后会由前端路由器自动识别当前路径，跳转至对应页面，即可实现和开发环境一致的刷新访问体验。
• 本地复现测试对齐技巧：本地用http-server验证构建产物时，启动命令需要追加SPA兜底参数：http-server ./www -p 8080 --proxy http://localhost:8080?，即可模拟Azure静态托管的配置效果，和ng serve的运行行为保持一致。

部署避坑提醒 #

• 开启静态网站托管后，构建产物必须上传至系统自动生成的$web容器内，不要上传到其他普通公开Blob容器。否则不仅会触发之前遇到的长hash文件名400报错，还会因为路径前缀不匹配导致静态资源加载异常。

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