uniapp打包网页白屏：路由模式导致HTML5 History模式失效

Question

在使用 UniApp 打包 Web 应用时，常因路由模式配置不当导致页面白屏。当采用 HTML5 History 模式且未正确配置服务器或缺少降级处理时，页面刷新后资源路径错误，静态服务器无法正确返回 index.html，导致路由失效、应用白屏。此外，H5 端未在 manifest.json 中合理设置 base 字段或服务器未开启 URL 重写支持，亦会加剧该问题。此现象多见于 Nginx 或 Apache 服务器部署初期，开发者易忽略 history 模式的运行依赖，误以为与开发环境表现一致。解决关键在于确保服务端配置支持路径回退至入口文件，并根据部署路径正确设置路由 base。

Answer 1

一、UniApp Web 打包中路由模式导致白屏问题的深度解析与解决方案

1. 问题现象：为何刷新页面后出现白屏？

在使用 UniApp 构建 H5 应用时，开发者常选择 HTML5 History 模式 来实现更友好的 URL 路径（如 /user/profile），而非默认的 Hash 模式（#/user/profile）。然而，一旦部署到生产环境并刷新页面，应用常出现白屏现象。

根本原因在于：History 模式依赖于前端路由机制，当用户直接访问或刷新非根路径（如 /user/profile）时，请求会发送至服务器。若服务器未配置 URL 重写规则，则无法识别该路径，返回 404 错误或静态资源缺失，导致浏览器加载失败，最终呈现白屏。

2. 技术背景：History 模式与服务端协作原理

• 前端路由：Vue Router 的 history 模式通过 pushState 和 replaceState 实现无刷新跳转。
• 服务端盲区：服务器仅知道物理文件路径，无法感知前端路由的存在。
• 入口统一：所有非资源请求应被重定向至 index.html，由前端接管路由逻辑。
• base 配置：若应用部署在子路径下（如 https://example.com/app/），需在 manifest.json 中设置 "h5" → "router" → "base" 字段。

3. 常见错误场景与排查清单

序号	错误配置	表现症状	影响范围
1	未开启 Nginx rewrite	刷新 /about 返回 404	全站路由失效
2	base 路径设置错误	资源加载 404（JS/CSS）	首页即白屏
3	Apache 未启用 mod_rewrite	静态服务器返回目录列表	安全风险+白屏
4	CDN 缓存了 404 页面	即使修复后仍白屏	发布延迟生效
5	开发环境正常但生产异常	误判为“打包问题”	调试方向错误
6	多级子路径部署未调整 base	路由错位，资源路径错乱	功能完全不可用
7	未处理 404 回退逻辑	API 请求被重定向至 index.html	接口调用失败
8	混合使用 hash 与 history	路由状态混乱	用户体验断裂
9	manifest.json 格式错误	配置未生效	隐性故障
10	构建输出路径与部署路径不一致	资源 404	全量加载失败

4. 解决方案：服务端配置示例

Nginx 配置片段

server {
    listen 80;
    server_name your-domain.com;
    root /var/www/uniapp-dist;
    index index.html;

    # 关键：所有非资源请求回退到 index.html
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 避免 API 请求被重写
    location /api/ {
        proxy_pass http://backend;
        internal: false;
    }

    # 静态资源缓存优化
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Apache (.htaccess) 配置

RewriteEngine On
RewriteBase /
RewriteRule ^index\.html$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.html [L]

5. 前端配置：manifest.json 中的 base 设置

当应用部署在子路径下（如 https://example.com/my-app/），必须在 manifest.json 中明确设置 base：

{
  "h5": {
    "router": {
      "mode": "history",
      "base": "/my-app/"
    }
  }
}

此配置确保 Vue Router 正确拼接路径，并影响 Webpack 构建时的资源引用前缀（如 <script src="/my-app/static/js/app.js">）。

6. 架构级思考：如何设计可移植的部署方案？

1. 引入环境变量动态生成 base 路径，避免硬编码。
2. 使用 CI/CD 流水线自动注入部署上下文信息。
3. 构建时生成 deployment.config.js 提供运行时路径元数据。
4. 结合监控系统捕获 404 请求，分析路由异常模式。
5. 实施灰度发布策略，在边缘节点验证路由重写规则。
6. 采用微前端架构时，需协调主应用与子应用的 base 冲突。
7. 利用 Service Worker 实现客户端兜底路由恢复机制。
8. 对 CDN 层面进行路径重写，减轻源站压力。
9. 建立部署前检查清单，包含路由模式验证项。
10. 文档化不同环境下的 base 与服务器配置映射关系。

7. 可视化流程：白屏问题诊断路径

graph TD A[用户刷新页面] --> B{URL 是否为非根路径?} B -- 是 --> C[浏览器发起 HTTP 请求] B -- 否 --> D[正常加载 index.html] C --> E[服务器查找对应资源] E --> F{是否存在物理文件?} F -- 是 --> G[返回资源] F -- 否 --> H[是否配置 URL 重写?] H -- 否 --> I[返回 404 → 白屏] H -- 是 --> J[返回 index.html] J --> K[前端路由接管] K --> L[渲染目标页面] I --> M[开发者排查服务器配置] M --> N[修正 rewrite 规则] N --> J