Iframe 内嵌 Vue 应用因 `visibilitychange` 事件导致 URL 参数丢失问题排查与解决方案

Iframe 内嵌 Vue 应用因 visibilitychange 事件导致 URL 参数丢失问题排查与解决方案

一、问题描述

1. 环境与背景

• 主应用 (项目 A) : 一个 Web 应用，通过 <iframe> 标签嵌入了我们的 Vue.js 项目。
• 子应用 (Vue 项目) : 运行在 iframe 中，需要从 URL 的查询参数中获取租户 ID (tenant) 来进行初始化。
• 关键功能 :
  • 子应用中有一个 getUrlTenantData 函数，用于从 location.href 中解析 tenant 参数。如果无法获取，则返回一个默认值 'US'。
  • 子应用中实现了一个 visibilitychange 事件监听器。当用户切换浏览器标签页，导致页面从"不可见"变为"可见"时，会执行一个页面重载或替换的逻辑。

2. 具体现象

当主应用通过 src 属性为 iframe 设置了包含 tenant 参数的 URL (例如: .../your-page?tenant=QA) 时：

1. 首次加载 : 页面正常加载，getUrlTenantData 函数能成功获取到 tenant 的值 'QA'。
2. 切换 Tab 后: 用户切换到另一个浏览器标签页，然后再切换回来。
3. 问题出现 : iframe 内的页面被刷新，此时调用 getUrlTenantData 函数，获取到的值却是默认的 'US'，而不是预期的 'QA'。
4. 令人困惑的一点 : 通过浏览器开发者工具检查 Elements 面板，<iframe> 标签的 src 属性依然显示为 .../your-page?tenant=QA，但应用内部获取到的 tenant 却已丢失。

3. 问题步骤回顾

步骤	现象
首次加载	网址 .../your-page?tenant=QA → getUrlTenantData() 返回 QA
切换浏览器标签页	iframe 页重新挂载
重新读取 tenant	getUrlTenantData() 只得到默认值 US
调试困惑	DevTools Elements 中 <iframe src="...?tenant=QA"> 未变，却已丢失 tenant

二、相关代码

1. getUrlTenantData 函数

此函数负责从当前 URL 中解析 tenant 参数。

export const getUrlTenantData = (): string => {
  try {
    const tenant = new URL(location.href).searchParams.get('tenant')
    return tenant || 'US'
  } catch (error) {
    console.log('getUrlTenantData error：', error)
    return 'US'
  }
}

2. visibilitychange 事件处理逻辑

这段代码在组件挂载时添加事件监听，并在 Tab 切换回来时，用初始 URL 替换当前 URL。

import { onMounted, onUnmounted } from 'vue'
import { useRouter } from 'vue-router'

const router = useRouter()

// 关键点：这里只保存了 URL 的路径部分，丢失了查询参数
const initialUrl = location.pathname

function handleVisibility() {
  if (document.visibilityState !== 'visible') return
  const currentUrl = router.currentRoute.value.fullPath
  if (currentUrl !== initialUrl) {
    console.log('Tab 已经被激活 ▶️', 'currentUrl', currentUrl, 'initialUrl', initialUrl)
    router.replace(initialUrl)
  }
}

onMounted(() => {
  document.addEventListener('visibilitychange', handleVisibility)
})

onUnmounted(() => {
  document.removeEventListener('visibilitychange', handleVisibility)
})

三、根本原因分析

问题的根源在于 visibilitychange 事件处理逻辑中对初始 URL 的保存方式不正确。

const initialUrl = location.pathname** 是罪魁祸首。**

• location.pathname 只会获取 URL 中的路径部分（例如 /your-page），而会完全丢弃 查询字符串部分（例如 ?tenant=QA）。

1. 问题发生流程

1. 初始加载 :
   • iframe 以 .../your-page?tenant=QA 加载。
   • 组件挂载，执行 const initialUrl = location.pathname，此时 initialUrl 被赋值为 /your-page。 tenant** 信息在此刻已经丢失**。
2. 切换 Tab : 用户离开再回来，触发 visibilitychange 事件。
3. 执行 handleVisibility:
   • 函数检查到 document.visibilityState 为 'visible'。
   • 执行 router.replace(initialUrl)，这实际上是在执行 router.replace('/your-page')。
4. Iframe 内部地址被改变 :
   • Vue Router 将 iframe 内部的 window.location 地址替换为了一个不包含任何查询参数的新地址。
   • 这个地址变更导致了 iframe 内容的刷新或重载。
5. 获取 tenant:
   • 在页面刷新后，getUrlTenantData 函数被调用。
   • 它读取的是刷新后 的、iframe 内部当前 的 location.href，这个地址已经没有 tenant 参数了。
   • 因此 searchParams.get('tenant') 返回 null，函数最终返回了默认值 'US'。

2. 为何 Elements 面板的 src 不变？

• 开发者工具 Elements 面板中显示的 <iframe> 标签属于父应用的 DOM 。它的 src 属性反映的是父应用设置的初始加载地址。
• 当 iframe 内部 通过 history.pushState 或 history.replaceState (Vue Router 内部会调用它们) 改变自己的 URL 时，这属于内部导航，它不一定会反向更新父应用 DOM 中 <iframe> 标签的 src 属性。
• 因此，我们看到了 src 属性"看似"正确，但 iframe 内部的 location.href 已经"实质"改变的现象。

四、解决方案

1. 保留完整路径

import { onMounted, onUnmounted } from 'vue'
import { useRouter } from 'vue-router'

const router     = useRouter()
const initialUrl = router.currentRoute.value.fullPath

function handleVisibility () {
  if (document.visibilityState !== 'visible') return
  const cur = router.currentRoute.value.fullPath
  if (cur !== initialUrl) router.replace(initialUrl)
}

onMounted   (() => document.addEventListener('visibilitychange', handleVisibility))
onUnmounted (() => document.removeEventListener('visibilitychange', handleVisibility))

2. 缓存信息

export const getUrlTenantData = (): string => {
  const cache = sessionStorage.getItem('tenant')
  if (cache) return cache

  const tenant = new URL(location.href).searchParams.get('tenant')
  if (tenant) { sessionStorage.setItem('tenant', tenant); return tenant }
  return 'US'
}

3. 父子页面通信

// 父页面
iframeEl.contentWindow.postMessage({ tenant: 'QA' }, '*')

// 子页面
window.addEventListener('message', e => {
  if (e.data?.tenant) sessionStorage.setItem('tenant', e.data.tenant)
})

五、验证结果

测试项	修复前	修复后
首次加载	QA	QA
切换 Tab 后 tenant 值	US	QA
DevTools <iframe src>	始终 QA	始终 QA
Console contentWindow.location.href	丢 query	保留 query

六、总结与关键点

• 在处理单页应用（SPA）的 URL 时，必须精确理解 location.pathname、location.search 和 location.href 之间的区别。
• 当需要获取包含查询参数的完整路径时，应使用 Vue Router 提供的 route.fullPath 属性。
• 需要警惕 iframe 的一个特性：其内部的 window.location 可以独立于父页面 DOM 中 src 属性进行改变。调试时应以 iframe 内部上下文的 location.href 为准。
• SPA 中若依赖查询串，应缓存关键参数，或在父子页面间显式同步。