uni-app怎么解决H5页面刷新404 uni-app伪静态配置解决办法【避坑】-uni-app-PHP中文网

uni-app h5刷新404的根本原因是web服务器未正确配置路由回退至index.html，需确保nginx rewrite规则、publicpath与pages.json中h5.router.base三者严格一致，并在cdn及云存储中启用单页应用支持。

uni-app怎么解决h5页面刷新404 uni-app伪静态配置解决办法【避坑】

uni-app H5 刷新 404 的根本原因

不是代码写错了，是 Web 服务器没找到 index.html 对应的路由。uni-app H5 构建后是纯静态文件，所有路由（比如 /user/profile）都靠前端路由（vue-router）接管，但浏览器直接刷新时，请求会打到服务端——而 Nginx/Apache 默认只认真实存在的文件路径，/user/profile 这种路径下没有对应文件，就返回 404。

Nginx 伪静态配置必须加 rewrite 规则

不能只靠 try_files，尤其在子目录部署或带 base path 场景下，漏掉重写逻辑就会 fallback 失败。

uni-app

uni-app 是基于 Vue 的跨端开发框架，适合开发 H5、App、小程序、鸿蒙和多端业务应用。

下载

location / { try_files $uri $uri/ /index.html; } 只适用于根目录部署，且依赖 $uri 能命中资源；一旦页面路径含多级（如 /app/user），而构建时 publicPath 设为 /app/，Nginx 就可能找不到 /app/index.html
正确做法是显式 rewrite 所有非资源请求回 index.html：
```
location ^~ /app/ {
  try_files $uri $uri/ /app/index.html;
}
```

更稳妥的通用写法（匹配所有非静态资源后缀）：

location / {
  try_files $uri $uri/ @fallback;
}
location @fallback {
  rewrite ^(.*)$ /index.html last;
}

uni-app 的 `router` 配置和 `publicPath` 必须对齐

如果 H5 部署在子路径（如 https://example.com/myapp/），但 vue.config.js 里没设 publicPath: '/myapp/'，或者 pages.json 中 h5.router.base 没同步，就会导致 JS/CSS 加载 404，连首页都进不去，更别说刷新了。

vue.config.js 中必须显式声明：

module.exports = {
  publicPath: process.env.NODE_ENV === 'production' ? '/myapp/' : '/'
}

pages.json 中启用 base 路由：

"h5": {
  "router": {
    "base": "/myapp/"
  }
}

注意：两个配置值必须完全一致，末尾斜杠不能一个有、一个没有

本地开发 `serve` 不报错 ≠ 线上不 404

uni-app 自带的 npm run serve 是用 webpack-dev-server，它默认开启 historyApiFallback，自动把所有 404 重定向到 /index.html —— 所以本地刷多少次都正常。但这只是开发服务器的“蜜糖”，上线后换 Nginx/Apache 就立刻暴露问题。

上线前务必在本地模拟真实环境：用 npx http-server -p 8080 -c-1 dist/build/h5 启动静态服务，再手动访问子路径并刷新，看是否 404
如果用了云厂商（如腾讯云 COS、阿里云 OSS），它们的静态托管也需单独开启「单页应用支持」或填写「错误文档为 index.html」，不是上传完就完事
CDN 缓存了旧的 404 响应？清空 CDN 缓存，尤其是 404 状态码可能被缓存长达 24 小时

实际踩坑最多的地方，是把 publicPath 和 Nginx 的 location 前缀当成一回事来配，却忽略了 try_files 查找路径时不会自动补前缀——它查的是磁盘上的真实相对路径。