uniapp H5 使用 history路由模式 本地调试正常，但是打包上传云托管后页面不显示内容

欢迎到专业群（ uni-app 官方技术交流群 1 ） 咨询，群中有相关专业的管理员和群友。

这个问题主要是 history 路由模式下，服务器没有正确配置导致的。本地调试正常是因为开发服务器默认处理了路由 fallback，而云托管环境需要手动配置。

核心原因

history 路由模式下，url 中不包含 #，例如 https://example.com/pages/index/index。当用户直接访问这个地址或刷新页面时，服务器会尝试寻找 /pages/index/index 这个实际文件。因为单页应用只有 index.html 一个入口文件，服务器找不到对应文件就会返回 404 或空白。

解决方案

需要根据你使用的云托管服务类型进行配置。

1. 如果使用的是 uniCloud 前端网页托管（阿里云/支付宝云）

在 uniCloud 控制台的前端网页托管中，找到“参数配置”，设置 404 页面为 index.html。这样当访问路径找不到文件时，服务器会返回 index.html 的内容，前端路由就能接管并正确渲染页面。

参考文档：前端网页托管，H5使用history路由模式，除了首页刷新白屏，文件不存在解决办法

2. 如果使用的是支付宝云托管且上述方法无效

支付宝云在配置 404 页面后可能仍然返回 302 重定向到 /index.html，导致 window.location.pathname 变成 /index.html，路由无法匹配。可以在入口文件（如 main.js）中，在创建路由之前添加如下处理：

// 仅 h5 平台  
if (window.location.pathname === '/index.html') {  
  window.history.replaceState({}, '', '/');  
}

本助手使用国产模型，生成代码可能不准确。专业的代码生成需要全球顶尖的AI Coding模型。推荐使用uni-agent

3. 如果使用的是自建 nginx 服务器

在 nginx 配置文件中添加 try_files 指令，将所有非静态资源请求都指向 index.html：

location / {  
  try_files $uri $uri/ /index.html;  
}

本助手使用国产模型，生成代码可能不准确。专业的代码生成需要全球顶尖的AI Coding模型。推荐使用uni-agent

4. 其他云服务商（如腾讯云、阿里云对象存储等）

同样需要配置 404 页面或路由重写规则，将所有找不到的路径都指向 index.html。具体配置方式参考对应服务商的文档。

5. manifest.json 中的 base 配置

如果项目不是部署在域名根目录，需要在 manifest.json 的 h5 配置中设置正确的 base 值：

"h5": {  
  "router": {  
    "mode": "history",  
    "base": "/你的子路径/"  
  }  
}

本助手使用国产模型，生成代码可能不准确。专业的代码生成需要全球顶尖的AI Coding模型。推荐使用uni-agent

排查步骤

1. 打开浏览器开发者工具，查看 network 面板
2. 直接访问一个非首页的页面路径，观察服务器返回的是 404 还是 index.html 的内容
3. 如果返回 404，说明服务器 fallback 配置未生效
4. 如果返回了 index.html 但页面空白，检查控制台是否有 js 资源 404 错误，可能是静态资源路径问题

相关问题参考

如果遇到 process is not defined 报错，可以参考：uniapp 打包 H5 后点击跳转操作会报错process is not defined