Vue部署OSS后二级路由刷新白屏

Question

Vue项目部署到阿里云OSS（静态托管）后，访问二级路由（如 `/user/profile`）直接刷新页面时出现白屏，控制台无报错但路由未匹配、组件未渲染。根本原因是OSS作为纯静态对象存储，不具备服务端路由能力——当用户直接请求 `/user/profile` 时，OSS会尝试查找名为 `user/profile.html` 的文件（实际不存在），返回404或默认首页（如 `index.html`），但此时 Vue Router 处于 `history` 模式，无法自动接管该 URL 并触发路由匹配。虽已将 `index.html` 设为默认首页且配置了 `<base href="/" />`，仍因缺少服务端重定向规则（如 Nginx 的 `try_files` 或 Apache 的 `FallbackResource`），导致 Vue 的前端路由“接管失败”。该问题在本地 `npm run serve` 下正常，上线后暴露，是典型的静态部署与 history 模式不兼容场景。

Answer 1

```html

一、现象层：白屏与路由失效的表征观察

• 用户直接访问 /user/profile（非从首页跳转）时，页面空白，无控制台报错；
• Network 面板可见请求返回 200 OK 的 index.html，但 Vue 实例未挂载对应组件；
• router.currentRoute.value.path 仍为 "/" 或为空，router.isReady() 已 resolve；
• 本地 npm run serve 下一切正常——暴露了「开发服务器 vs 静态托管」的本质差异。

二、机制层：Vue Router history 模式与 OSS 静态服务的冲突原理

OSS 不是 Web 服务器，而是对象存储服务。其静态网站托管功能仅支持：

能力	OSS 支持	说明
默认首页重定向	✓（index.html）	仅对 / 请求生效
路径前缀匹配重写	✗	无 try_files $uri $uri/ /index.html 等语义
404 自定义回退	✓（但仅限 404 页面 HTML）	无法将所有 404 重定向至 index.html 供 Vue Router 接管

三、验证层：关键诊断步骤与证据链

1. 在 OSS 控制台查看「静态网站托管」配置：确认已启用，且默认首页设为 index.html；
2. 手动请求 https://your-bucket.oss-cn-hangzhou.aliyuncs.com/user/profile.html → 返回 404；
3. 请求 https://your-bucket.oss-cn-hangzhou.aliyuncs.com/user/profile/（末尾带斜杠）→ 返回 404（OSS 不自动补 index.html）；
4. 检查构建产物：dist/user/profile.html 不存在 → 证实非文件级路由，纯前端路由。

四、解法层：四种生产级可行方案对比

graph LR
A[问题根源] --> B{是否可控服务端？}
B -->|否：纯 OSS| C[方案1：改用 hash 模式]
B -->|是：加 CDN 或反向代理| D[方案2：阿里云 CDN + 自定义 404 重定向]
B -->|可接受构建时预生成| E[方案3：SSG 预渲染关键路由]
B -->|架构允许微服务化| F[方案4：Nginx/SLB 反向代理兜底]

五、实施层：推荐方案（CDN + 404 重定向）详细配置

# 阿里云 CDN 控制台操作路径：
# 1. 添加域名 → 回源设置指向 OSS Endpoint；
# 2. 缓存配置 → 关闭对 HTML 的缓存（或设置短 TTL）；
# 3. 【重要】错误页面配置：
#    - 状态码：404
#    - 响应动作：重定向
#    - 重定向 URL：/index.html
#    - HTTP 状态码：302（或 200 + rewrite，取决于 CDN 版本）

六、加固层：配套必须项清单

• ✅ vue.config.js 中确保 publicPath: '/'（非 './'）；
• ✅ index.html 内含 <base href="/">；
• ✅ Router 构造时启用 scrollBehavior 避免滚动丢失；
• ✅ 添加路由守卫捕获未匹配路径：router.beforeEach((to, from, next) => { if (!routes.some(r => r.path === to.path)) next('/404'); else next(); })。

七、演进层：面向未来的架构建议

对于中大型 Vue 应用，建议在部署层引入轻量网关：

• 使用阿里云 API 网关 或 函数计算 FC + Custom Domain 承接入口，实现动态 fallback；
• 结合 vite-plugin-ssg 实现增量静态生成（ISR），兼顾 SEO 与首屏性能；
• 将路由元信息外置为 JSON，由网关预读并注入 HTML，实现服务端驱动的客户端 hydration。

```