document.location 深度解析：属性边界、跳转取舍与工程实践

document.location 这个名字几乎每个写过前端的人都见过但真正把它当回事、把它的边界条件摸清楚的人并不多。多数时候我们只是location.href /list一下就完事直到某天测试同学拿着手机过来问为什么我点返回又跳回登录页了或者运营说筛选条件分享给同事之后全丢了才会回头认真看一眼这个对象。它属于那种天天用、很少懂的 API看起来像字符串写起来像变量实际上是一个会被浏览器实时更新的宿主对象。这篇内容我想把它彻底拆开讲一遍从它为什么会被写成 Document.location到各个属性在真实项目里的取值规则再到 assign、replace、reload 三个方法的取舍最后给出几个可以直接抄走的实现和一份排查速查表。不管你是刚接触 DOM 的新手还是已经写过几年业务代码、被路由和参数折腾过的老手应该都能从中找到点能立刻用上的东西。1. 这个被写成 Document.location 的对象到底是谁1.1 从 window 和 document 两个入口说起先把最容易混淆的一点讲清楚document.location和window.location指向的是同一个对象不是两个东西也不是两份数据。早期 DOM 规范把地址相关的接口挂在 document 上后来浏览器模型调整地址信息归到了 window 下面但为了不破坏已有的页面代码document.location这个别名一直保留着。所以你在控制台里敲document.location window.location返回的是true。这一点很重要因为有些老文档、老博客里写的是Document.location首字母大写那种写法初学者看到会以为是某个构造函数或者类实际上浏览器里并不存在一个可以直接new的Document.location你在代码里写document.location才是能跑的那个。我见过有人在面试里被问到这两者的区别答成一个是文档的一个是窗口的取到的值不一样这个说法是错的。既然是同一个对象为什么还有人习惯写document.location纯粹是历史惯性。现在新写的代码统一用window.location或者直接写location更清晰因为在模块作用域里location会优先取全局那个除非你本地声明了一个同名变量把自己坑了。这一点后面会专门说是个很隐蔽的 bug 来源。1.2 它为什么不像普通对象location最反直觉的地方在于它不是那种你存什么就读什么的普通对象。你给location.href赋值实际发生的是导航——浏览器开始卸载当前页面、加载新地址。读location.href的时候拿到的也不是你上次写进去的值而是浏览器当前地址栏里那个 URL 的序列化结果。也就是说这个对象的属性是活的会随着地址变化自动更新。再往深一层它的属性还不可枚举。你在控制台里Object.keys(location)多数浏览器返回空数组for...in也遍历不出东西。但location.href、location.pathname这些又能正常访问。这是因为Location在规范里被定义成一个特殊对象属性挂在原型上并且做了访问器处理。知道了这一点你就能理解为什么JSON.stringify(location)得到的是{}而不是一串地址——很多人想把 location 直接序列化存起来结果拿到空对象就是栽在这里。正确的做法是先取location.href再处理。还有一点值得提醒跨源的时候location的读权限是被限制的。你在父页面里访问一个跨域 iframe 的contentWindow.location.href浏览器会直接抛安全异常。但写是允许的你可以把跨域 iframe 导航到别的地址。这个不对称的行为在嵌入第三方页面、做统一登出跳转时经常会遇到理解了就不会觉得莫名其妙。1.3 属性全景对照在动手写代码之前先把各个属性的含义和返回值形态过一遍。下面这张表是我自己整理常用的部分建议收藏遇到地址处理的需求先对照看一眼再写。属性返回值示例说明与常见误区hrefhttps://demo.local:8080/list?page2#top完整地址读写都走它赋值会触发导航originhttps://demo.local:8080协议加主机加端口不含路径默认端口会被省略protocolhttps:带冒号判断协议时不要漏掉这个冒号hostdemo.local:8080主机名加端口默认端口时不显示端口hostnamedemo.local只有主机名不含端口port8080使用默认端口时返回空字符串不是80或443pathname/list以斜杠开头做了百分号编码search?page2带前导问号没有查询串时返回空字符串hash#top带井号没有片段时返回空字符串ancestorOrigins类数组部分浏览器支持用于取祖先页面来源表里最容易踩的两个点port在默认端口时是空串所以你不能用location.port 443去判断是不是安全连接得看protocolsearch和hash都带前缀符号拼接的时候如果自己再加一遍问号或井号就会出现??page1这种畸形地址服务器解析直接出错。2. 属性读取的深水区每个字段的边界条件2.1 href 与 origin最常用也最容易出错href是使用频率最高的一个属性但它的行为在不同场景下差异不小。读取的时候浏览器返回的是序列化之后的地址路径里的中文、空格会被百分号编码而查询串和片段里的字符处理规则又略有不同。也就是说你在地址栏里看到的是?keyword测试读location.href可能拿到?keyword%E6%B5%8B%E8%AF%95。如果你打算把href直接丢给后端做统计或者拼签名务必先想清楚需不需要解码否则后端拿到的是一串编码字符做匹配的时候对不上。origin是我个人最推荐用来做同源判断的属性因为它语义明确、不用自己拼。但要注意两个边界一是file://协议下它返回的是file://这种形态不同浏览器表现不完全一致二是在某些老版本浏览器里这个属性根本不存在取出来是undefined。如果你需要兼容比较老的环境可以退化成location.protocol // location.host自己拼一个注意默认端口在这个拼法下也不会出现跟origin的行为是一致的。还有一个小细节href赋值和location.assign()在绝大多数情况下等价都会在历史记录里新增一条。但如果你赋的值是javascript:开头的伪协议行为就完全不同了浏览器会把它当脚本执行。这种写法在十几年前很流行现在基本属于该被淘汰的用法既不利于内容安全策略也不好调试。我现在的习惯是任何跳转都不要用伪协议用void 0或者绑事件的方式替代。2.2 protocol、host、hostname、port 的取舍这四个属性经常被混用实际分工很清晰。判断当前页面是不是安全协议看protocol比较的时候必须带冒号写成location.protocol https:。如果你想做环境判断比如测试环境走了特殊端口、生产环境走默认端口那就得用host或者port而不是hostname因为hostname会把端口吃掉。这里有个很实际的坑用port判断环境的时候一定要意识到默认端口返回空串。我自己就遇到过本地调试起在 80 端口写了个if (location.port 80)的判断死活不生效后来打印出来才发现是空字符串。正确的写法是把空串也当成默认端口的一种情况来处理。再一个场景是拼接接口地址。很多人喜欢这么写const api location.protocol // location.host /api这个写法本身没问题但如果你的页面是通过某种反向代理访问的host和实际后端地址未必一致直接拼出来的地址可能会打到错误的机器上。我的建议是接口的基础地址一律走配置或者构建时的环境变量不要从location里现算location只用来做当前页面在哪的判断不要拿它推导后端拓扑。2.3 pathname、search、hash 的原始值与编码pathname拿到的是编码后的路径字符串/搜索会变成/%E6%90%9C%E7%B4%A2。如果你要做路由匹配比如判断当前是不是详情页直接用pathname.startsWith(/detail/)是安全的因为前缀部分都是 ASCII。但如果路径里包含中文参数就得先decodeURIComponent再比较注意是decodeURIComponent而不是decodeURI后者不会解码保留字符。search的处理是重灾区。它的原始值是带问号的完整查询串最省事的解析方式是用URLSearchParams但这个东西有两个必须知道的行为第一它会把解析成空格这是因为表单编码的历史遗留第二它对重复的键用get只返回第一个要拿全部得用getAll。我处理过一个线上问题就是从地址里带一个含的参数前端读出来变成了空格后端校验签名一直失败查了大半天才定位到URLSearchParams的这个特性上。如果参数里确实可能出现取值之后要么在源头做一次编码把编成%2B要么读出来之后不要做二次加工直接原样透传。hash同理返回带井号的片段。它在不同浏览器下的编码表现略有差异有的会返回编码后的字符有的保留原文。稳妥写法是读出来先去掉井号再decodeURIComponent兜一层 try/catch因为格式不正确的编码序列会直接抛异常把整个初始化流程打断。2.4 用 new URL 补位解析相对地址的正确姿势location本身只能告诉你当前在哪没法帮你解析我要去哪。真正做地址解析应该用URL构造函数。比如后端返回一个相对路径../detail/1024你想知道它的绝对地址可以这么写const target new URL(../detail/1024, location.href).href;第二个参数是基准地址传location.href就能得到正确的解析结果。这个东西比手写字符串拼接靠谱得多它会帮你处理掉多余的斜杠、.和..、默认端口归一化等问题。我现在的习惯是只要涉及地址拼接、参数增删、同源判断一律先new URL()出来再说避免手工操作字符串。这里有个容易忽略的点在页面里写了base标签的时候相对链接的解析基准会变成base指定的地址但location赋值时的解析基准仍然是文档本身的地址。这两者不一致的时候比如你的 base 指向了 CDN而 location 还是主站如果代码里既用了a href相对路径又用了location.href 相对路径跳转结果可能完全不一样。我个人的建议是能不用base就不用非要用的话所有跳转一律用new URL(path, location.href)显式指定基准别依赖浏览器的默认行为。3. 三种跳转方式的取舍assign、replace、reload3.1 赋值 href 与 assign 到底差在哪从行为上看location.href url和location.assign(url)几乎完全一样都会在历史记录栈里压入一条新记录用户点返回能回到原页面。差别只在可读性和一个边缘情况assign是个方法调用语义上更明确我正在主动导航而赋值可能被误认为在修改一个普通属性。另外如果传入的地址不合法比如包含了非法字符两者的报错时机和形式可能略有不同但这属于极少见的边角。我的习惯是简单跳转直接赋值href代码短、意图清楚如果是封装一个通用的跳转函数内部用assign更正式一些。真正需要区分的是下一个方法。3.2 replace 必须用的场景location.replace(url)的关键特性是不新增历史记录它会把当前这条历史记录替换掉。什么时候必须用它我总结了三类典型场景。第一类是登录失效后的跳转。用户在一个列表页停留太久token 过期了点了个按钮结果接口返回未授权前端跳登录页。这时候如果用的是href赋值用户登录成功点返回会回到那个列表页页面又发现未授权再跳登录形成死循环。用replace就不会留下这条过期页面的记录返回逻辑干净很多。第二类是中间跳转页。比如做一次性的授权回调落地页读完地址里的凭证就立刻跳去目标页这种页面没有任何返回的价值用replace可以避免用户返回时看到一个空白或者已经在自动跳转的页面。第三类是防止表单重复提交后的回退。提交成功之后跳到结果页如果用户点返回回到表单页很可能会再点一次提交。用replace把表单页从历史里换掉能减少这类重复操作。顺带提一句history.replaceState它和location.replace完全不是一回事前者只改地址栏和当前历史记录不触发页面加载是单页应用的标准操作后者是实打实的导航会重新加载文档。这两个名字很像但场景完全不同别混。3.3 reload 的缓存坑与正确刷新姿势location.reload()重新加载当前文档。很多人包括几年前的我以为写location.reload(true)能强制跳过缓存从服务器重新拉取。这个参数在规范里早就没有了Chrome 里传了也不生效Firefox 里甚至可能报错或者行为不一致。所以如果你的需求是发版后让用户拿到新资源靠reload(true)是不靠谱的。真正管用的做法是从缓存策略上解决静态资源用带哈希的文件名配合长缓存HTML 入口文件设置成不缓存或者短缓存。页面层面的强制刷新只能用一次带随机参数的导航来实现比如const url new URL(location.href); url.searchParams.set(_t, Date.now()); location.replace(url.href);但这个方法副作用很明显地址栏会多一个参数用户分享出去会带上这个时间戳。所以只适合内部工具页面不适合对外产品。还有一个必须提醒的点调用reload之后页面上的脚本会全部重新执行任何没保存的表单内容、没提交的状态都会丢。我见过有同事在弹窗关闭的时候顺手写了个reload想刷新数据结果把用户填了半天的表单清空了。刷新数据请用接口重新拉取不要动整个页面。3.4 导航前的拦截与单页应用的冲突beforeunload事件常被用来在用户离开有未保存内容的页面时弹确认框。但现在的浏览器对这个行为限制很严必须用户有过交互点击、输入等之后才允许弹窗而且弹窗文案是浏览器固定的不能自定义。你写了event.returnValue 确定离开吗用户看到的也只是一句通用的提示。更要命的是在单页应用里路由跳转通常不会触发beforeunload因为压根没有发生文档级导航。所以如果你用beforeunload做离开页面提醒在单页应用的内部跳转里完全失效。要覆盖这种情况得在路由守卫里自己拦一道两条路都要堵上才算完整。4. 四个可以直接抄的场景实现4.1 筛选条件与地址栏状态同步列表页的筛选条件同步到地址栏是最典型的location应用场景。核心思路是读取时从search还原状态修改时写回search并且用replaceState而不是直接改location.search因为后者会触发一次完整导航页面重新加载体验很差。// 读取 function readFilters() { const params new URLSearchParams(location.search); return { keyword: params.get(keyword) || , page: Number(params.get(page)) || 1, status: params.get(status) || all }; } // 写入 function writeFilters(next) { const url new URL(location.href); Object.entries(next).forEach(([key, value]) { if (value || value null || value undefined) { url.searchParams.delete(key); } else { url.searchParams.set(key, String(value)); } }); history.replaceState(null, , url); }这段代码里有两个细节值得注意。一个是空值处理把空字符串也当作删除该参数可以让地址栏保持干净避免出现?keywordstatusall这种冗余。另一个是replaceState和pushState的选择筛选条件变化用replace比较合理因为用户不会希望每改一次筛选就多一条历史记录返回要按十几次但如果是翻页用pushState更符合预期因为返回上一页是翻页场景的常见操作。这个区别在需求评审时很少有人提但用起来体验差别很大。4.2 hash 路由的解析与监听在一些不需要引入完整路由库的小项目里用 hash 做路由是最轻量的方案。它的好处是兼容性好、不需要服务端配合缺点是地址不好看、对 SEO 不友好。解析逻辑大致如下function parseHash() { const raw location.hash.replace(/^#/, ); if (!raw) return { path: /, query: new URLSearchParams() }; const index raw.indexOf(?); const path index -1 ? raw : raw.slice(0, index); const query index -1 ? : raw.slice(index 1); let decodedPath path; try { decodedPath decodeURIComponent(path); } catch (e) { decodedPath path; } return { path: decodedPath, query: new URLSearchParams(query) }; } window.addEventListener(hashchange, render); window.addEventListener(DOMContentLoaded, render);这里用indexOf(?)和slice而不是split(?)是因为split之后如果后面的片段里还有问号取第二段会丢内容得再join回来不如直接按首个问号切。decodeURIComponent一定要包try/catch地址被手工改坏的时候会抛异常一抛整个渲染流程就断了页面白屏。监听这块也有个坑手动修改location.hash会触发hashchange但如果你用history.replaceState改了 hash是不会触发这个事件的。所以在混合使用两种写法的项目里经常出现地址变了但页面没更新的情况。我的做法是所有会改变路由状态的写法统一走一个函数在这个函数里手动调用一次渲染不要依赖事件。4.3 跳转白名单与多环境地址拼接只要你的跳转目标来自地址参数比如?redirectxxx就必须做白名单校验否则很容易被利用做开放重定向把用户引导到仿冒页面。这是安全评审的必查项也是最容易被遗漏的一项。const ALLOWED_HOSTS [demo.local, app.demo.local]; function safeNavigate(target) { let url; try { url new URL(target, location.href); } catch (e) { return false; } if (![http:, https:].includes(url.protocol)) return false; if (!ALLOWED_HOSTS.includes(url.hostname)) return false; location.assign(url.href); return true; }校验的关键是先解析再判断不要用字符串includes或者startsWith去匹配域名。因为https://demo.local.evil-site.test这种地址startsWith(https://demo.local)是能通过的但实际主机完全不同。new URL解析出来的hostname才是真实的主机名用它做精确匹配才安全。另外别忘了校验协议否则javascript:开头的地址也可能被放行。多环境地址拼接的做法我在前面提过这里再强调一下执行顺序优先用构建时的环境变量注入其次用页面上的配置对象最后才考虑从location推导。从location推导的前提是前后端部署在同一个域名下并且路径可预测一旦上了 CDN 或者做了多级代理这个假设就不成立了。4.4 锚点滚动与平滑定位点击目录跳到页面某个标题是hash最原始的用途。设置location.hash section-2浏览器会自动滚动到idsection-2的元素位置同时留下一条历史记录。如果不希望留记录用history.replaceState加手动scrollIntoViewfunction jumpTo(id, smooth true) { const el document.getElementById(id); if (!el) return; el.scrollIntoView({ behavior: smooth ? smooth : auto, block: start }); history.replaceState(null, , # encodeURIComponent(id)); }用encodeURIComponent处理 id 是因为如果 id 里含中文或特殊字符不编码的话地址栏会出现非法字符某些浏览器会把它截断。另外history.replaceState传入的第三个参数如果是完整地址必须和当前页面同源否则会抛异常这点也常被忽略。还有一个体验细节页面刚加载时如果带着 hash浏览器会自动跳过去但如果页面内容是异步渲染的那一刻目标元素还不存在就会跳失败。稳妥做法是在数据渲染完成之后检查一次location.hash存在就手动调一次jumpTo。5. 排查实录那些让我加班到深夜的 location 问题5.1 参数丢失、乱码和加号变空格这三类问题的根因基本都在编码上。中文参数乱码通常是前端拼地址的时候没有编码或者后端解码方式和前端的编码方式不匹配。我的处理原则是任何进入地址栏的值都经过一次encodeURIComponent从地址栏读出来的值除非你确定格式安全否则不要盲目decodeURIComponent。加号变空格前面提过是URLSearchParams的规范行为。解决办法要么在源头编码要么干脆不用URLSearchParams自己写个简单的切分解析。我自己在需要严格保持原值的场景比如签名参数里会手写一个解析函数function parseSearchStrict(search) { const result {}; const raw search.replace(/^\?/, ); if (!raw) return result; raw.split().forEach(pair { const i pair.indexOf(); const key i -1 ? pair : pair.slice(0, i); const value i -1 ? : pair.slice(i 1); try { result[decodeURIComponent(key)] value; } catch (e) { result[key] value; } }); return result; }注意这里对值没有做解码保持原样避免把编码后的内容破坏掉。取到之后交给需要的地方自己解码。还有一个隐蔽的丢失场景地址里拼了#开头的参数比如?id1#/detail如果你的后端或者某些中间件把#后面的内容截断参数就丢了。所以参数一律放在?之后、#之前不要塞进 hash 里跨系统传递。5.2 回退历史错乱与 replaceState 的副作用历史记录错乱的典型表现是用户点返回要么原地不动要么跳到一个完全无关的页面要么反复在两个页面之间弹跳。常见根因有几个。一是在页面加载时无条件跳转。比如首页写了个检测逻辑没有登录就跳登录页登录页又检测到某个条件跳回首页两边互相跳。这种问题一定要在跳转前加个标记比如带上?fromlogin之类的参数打断循环或者用replace而不是assign。二是**pushState用得太多**。单页应用里每个小的交互都pushState用户会发现自己要按十几次返回才能出去。我的经验是只有用户会觉得这是一个新页面的操作才pushState比如打开详情、翻页、切换 Tab 视图纯筛选、排序、展开收起用replaceState。三是导航时机和异步操作冲突。页面正在发请求用户点了返回请求回来的回调里又调了一次跳转结果把用户从上一页拽回来。这类问题的修法是在跳转前判断页面是否还是活跃的可以在路由变化时置一个标志位回调里检查这个标志。5.3 hash 改了页面没反应这个问题我在带新人的时候被问过好几次。现象是代码里明明写了location.hash #detail地址栏也变了但页面内容没变化。原因通常是只写了设置 hash 的代码没写监听hashchange的逻辑或者是监听了但回调里读的是缓存的状态没有重新读location.hash。还有一种情况是地址栏里已经有#detail你又设置了一次同样的值这时候浏览器不会触发hashchange因为值没变。如果业务依赖这个事件来刷新数据就会失效。解决办法是在需要刷新的地方主动调用一次渲染函数不要依赖事件触发。顺带提一个容易忽略的hashchange在用户点浏览器前进后退时也会触发所以回调里一定要每次重新读取location.hash不能假设它和上次一样。我见过有人在回调里用了闭包捕获的旧值结果前进后退时页面显示的是错误的内容。5.4 常见问题速查表现象大概率原因处理方式参数里的中文变乱码拼接时未编码或编码方式不匹配入址前统一encodeURIComponent参数里的加号变空格URLSearchParams的表单编码规则源头把编成%2B或改用严格解析返回后回到登录页跳登录用了href赋值产生历史记录改用location.replace返回后反复弹跳两个页面互相条件跳转加断点标记或改用replace端口判断永远不成立默认端口时port返回空串把空串纳入判断分支改了 hash 页面没变没监听或被replaceState改了不触发统一封装渲染调用强制刷新无效reload(true)参数已废弃从缓存策略层面解决新窗口打开后被原页面操作缺少noopener链接加relnoopener相对地址跳到了错误位置页面存在base标签或路径层级算错用new URL(path, location.href)显式解析跨域 iframe 读取报错同源策略限制读操作只做写入读信息改走消息传递6. 收尾前必须想清楚的三件事6.1 新窗口打开与 opener 泄漏用window.open或者a target_blank打开新页面时新页面默认可以通过window.opener访问到原页面的window对象进而读取原页面的location甚至做导航。这是一个真实存在的风险点尤其是链接目标不完全可控的时候。|im_start|解决方式很简单window.open之后手动把opener置空a标签加上relnoopener现代浏览器对target_blank已经默认加了noopener但显式写出来更保险也不依赖浏览器版本。如果在某些老环境里还需要控制来源信息nosniff之外再配合来源策略头处理这部分属于服务端配置前端能做的就是别把控制权交出去。6.2 URL 长度与数据传递的边界地址栏不是数据总线长度是有上限的。不同浏览器和服务器对 URL 长度的容忍度不一样工程上一般把 2000 字符当成安全线。超过这个量级要么服务端配置调整要么换一种传递方式。我的处理原则是小状态筛选、分页、排序、Tab放地址栏好处是能分享、能刷新还原、能收藏大对象表格选中项、复杂表单草稿放sessionStorage或者服务端临时存储地址里只放一个短 id 做索引。这样既保留了可分享性又不会撑爆地址长度。之前有个项目把选中的几十个 ID 全拼在地址里用户选多了直接报 414后来改成存本地、地址只带一个 key问题才解决。6.3 敏感参数与来源信息地址栏里的内容是会被记录的浏览器历史、代理日志、统计系统、用户截图分享。所以任何敏感信息都不要放在search里。临时凭证、身份标识这类东西如果需要跨页面传递走sessionStorage或者服务端一次性票据更稳妥用完即弃。来源信息referrer也是一个容易被忽略的泄露渠道。默认情况下从 A 页面跳到 B 页面B 能通过来源信息知道 A 的地址如果 A 的地址里带了参数就等于泄露了。对外的链接可以在标签上加relnoreferrer切断这个传递或者在页面级别配置来源策略。我在实际项目里踩过的坑是一个内部报表页把筛选条件直接放在地址里其中包含了用户标识结果被分享到外部群之后对方的统计系统把这个地址连同标识一起记了下来。后来所有涉及用户维度的参数都改成了编码后的短哈希页面上再做一次映射还原虽然多了一步但安全边界清楚多了。最后分享一个小习惯每次写跟地址相关的逻辑我都会在浏览器控制台里手动改几次地址——加参数、删参数、改 hash、点前进后退——把这几种情况都过一遍再提测。这几分钟的操作能拦住后面一大半的返工。地址这个东西看起来简单但它是用户、浏览器、服务端三方共享的状态载体边界条件比绝大多数业务对象都多多验证几次总是不亏的。